Authentifizierung
Die MILKEE API verwendet Personal Access Tokens für die Authentifizierung. Diese Tokens werden über das Bearer-Token-Schema in HTTP-Headers übertragen.
API-Token erstellen
Automate Plan erforderlich
API-Tokens können nur mit einem aktiven Automate Abonnement erstellt werden. Upgraden Sie Ihr Abo in den MILKEE-Einstellungen.
Schritt 1: MILKEE-Einstellungen öffnen
- Melden Sie sich bei MILKEE an
- Navigieren Sie zu Einstellungen → API Tokens
- Klicken Sie auf Token erstellen
Schritt 2: Token konfigurieren
- Token Beschreibung: Geben Sie eine aussagekräftige Beschreibung ein (z.B. "Mobile App", "Integration", "Automation")
- Klicken Sie auf Erstellen
Schritt 3: Token sichern
Token nur einmal sichtbar
Der Token wird Ihnen nur einmal angezeigt. Speichern Sie ihn sicher!
Nach der Erstellung erhalten Sie einen Token wie:
abcdef123456789...Token verwenden
Fügen Sie den Token in den Authorization-Header Ihrer API-Requests ein:
Authorization: Bearer abcdef123456789...Beispiel-Request
curl -H "Authorization: Bearer abcdef123456789..." \
-H "Content-Type: application/json" \
https://app.milkee.ch/api/v2/companies/123/tagsFirmen-Kontext
Firmen-spezifische API
Alle API-Endpoints sind firmen-spezifisch. Sie müssen die {company} ID in der URL angeben.
Firmen-ID ermitteln
Ihre Firmen-ID finden Sie auf zwei Arten:
Methode 1: Über die MILKEE-Einstellungen
- Melden Sie sich bei MILKEE an
- Wählen Sie Ihre Firma aus dem Dropdown in der linken Navigation
- Navigieren Sie zu Einstellungen → Mein Unternehmen
- Scrollen Sie zum Feld "Firmen-ID für API" (direkt oberhalb des "Speichern"-Buttons)
- Kopieren Sie die ID durch Klicken in das Feld und Markieren des Textes
Hinweis:
Dieses Feld wird nur angezeigt, wenn Sie ein Automate Abonnement haben, welches für API-Zugriff erforderlich ist.
Methode 2: Über die API
curl -H "Authorization: Bearer abcdef123456789..." \
https://app.milkee.ch/api/v2/users/meDie Antwort enthält Ihre aktuelle Firma:
{
"id": 456,
"name": "Max Mustermann",
"email": "max@example.com",
"current_company": {
"id": 123,
"name": "Muster GmbH"
}
}URL-Struktur
Alle API-Endpoints folgen diesem Muster:
https://app.milkee.ch/api/v2/companies/{company}/{resource}Beispiel:
https://app.milkee.ch/api/v2/companies/123/tagsToken-Verwaltung
Token erneuern
Erneuern Sie einen Token über die MILKEE-Einstellungen:
- Gehen Sie zu Einstellungen → API Tokens
- Klicken Sie bei dem gewünschten Token auf Erneuern
- Bestätigen Sie die Aktion
Vorhandene Verbindungen invalidiert
Das Erneuern macht alle bestehenden Verbindungen ungültig. Aktualisieren Sie Ihre Anwendungen mit dem neuen Token.
Token löschen
Löschen Sie nicht mehr benötigte Tokens:
- Gehen Sie zu Einstellungen → API Tokens
- Klicken Sie bei dem gewünschten Token auf Löschen
- Bestätigen Sie die Aktion
Sofort ungültig
Gelöschte Tokens sind sofort ungültig und können nicht wiederhergestellt werden.
Sicherheitshinweise
Token-Sicherheit
- Geheim halten: Teilen Sie Ihre Tokens niemals öffentlich
- HTTPS verwenden: Senden Sie Tokens nur über sichere Verbindungen
- Regelmässig erneuern: Erneuern Sie Tokens regelmässig als Sicherheitsmassnahme
- Scope-Prinzip: Verwenden Sie separate Tokens für verschiedene Anwendungen
Berechtigungen
API-Tokens haben die gleichen Berechtigungen wie der erstellende Benutzer:
- Firmen-Zugriff: Nur auf Firmen, zu denen der Benutzer Zugriff hat
- Daten-Zugriff: Vollzugriff auf alle Daten der Firma
- Aktionen: Alle CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen)
Fehlerbehebung
@todo: Tests schreiben um sicherzustellen die Fehlermeldungen stimmen. Momentan wird auf login redirected z.Bsp.
401 Unauthorized
{
"message": "Unauthenticated."
}Mögliche Ursachen:
- Token fehlt oder ist ungültig
- Token ist abgelaufen
- Falsches Bearer-Token-Format
402 Payment Required
{
"message": "Dein Abo ist abgelaufen."
}Lösung: Erneuern Sie Ihr Automate Abonnement
403 Forbidden
{
"message": "This action is unauthorized."
}Mögliche Ursachen:
- Keine Berechtigung für die angeforderte Ressource
- Firmen-ID gehört nicht zum Token-Benutzer