Die CoffeeCup-API bietet eine JSON-basierte REST-API mit Zugriff auf alle Objekte sowie zahlreiche aggregierte Analyse-Feeds. Die REST-API kann verwendet werden, um CoffeeCup-Daten abzurufen, zu erstellen und zu bearbeiten.

Eine Alternative zum direkten API-Zugriff ist unsere Zapier-Integration, die einige der komplexeren Berechtigungen und Einstellungen abstrahiert und die Integration in verschiedene Workflows mit Drittanbieter-Apps ermöglicht.

Berechtigungen

Der Zugriff auf die API basiert auf den Berechtigungen der individuellen Benutzerkonten. Dies bedeutet, dass ein API-Entwickler, der sein persönliches CoffeeCup-Konto nutzt, nur auf die Ressourcen zugreifen kann, für die sein Konto berechtigt ist. Für maximale Flexibilität empfehlen wir, ein zusätzliches Utility-Benutzerkonto innerhalb von CoffeeCup mit den entsprechenden Berechtigungen für den API-Zugriff zu erstellen. Beachte, dass einige Modelle, wie z. B. Zeiteinträge, Eigenschaften haben, die nur vom Eigentümer/Ersteller des Objekts bearbeitet werden können.

API-Feed-Übersicht

Eine vollständige Liste aller verfügbaren API-Endpunkte in CoffeeCup findest du in unserem Swagger unter: https://dev.coffeecupapp.com.

Die automatisierte Swagger-Dokumentation zeigt die vollständige Liste der verfügbaren Feeds, enthält jedoch nicht alle möglichen Query-/Post-Parameter-Optionen. Wir empfehlen, den Netzwerkverkehr des Browser-Clients zu untersuchen, um die Abfrageparameter an deinen Anwendungsfall anzupassen.

Authentifizierung mit Swagger

Swagger kann auch zum Testen und Experimentieren genutzt werden. Verwende die Schaltfläche „Authorize“ oben rechts, um dich anzumelden.

⚠️ Wichtig: Das Login-Formular in Swagger ist nur einmal pro Sitzung aktiv. Wenn die Login-Seite nicht richtig angezeigt wird, lade die Seite neu und klicke erneut auf „Authorize“.

Nach der Autorisierung ändert sich die Schaltfläche zu einem Schloss-Symbol.

Du kannst dann einen Beispiel-Feed auswählen und eine Testanfrage mit den Schaltflächen „Try It Out“ und „Execute“ senden.

Wir empfehlen dringend, ein separates Entwicklungskonto/-domain zu verwenden, um API-Integrationen zu testen, die Daten verändern. Falls dein Unternehmen noch kein Entwicklungskonto hat, kontaktiere uns bitte.

Authorisierung

CoffeeCup verwendet OAuth 2.0 mit dem Grant-Typ „Password“. Im Rahmen der Token-Anfrage müssen Benutzer den CoffeeCup-Tenant über die Header „origin“ oder „companyurl“ identifizieren. Nach erfolgreicher Authentifizierung kann auf die API-Feeds mit Bearer-Authentication zugegriffen werden.

Token-Aktualisierung

Die folgenden Felder sollten formkodiert an den Endpoint oauth2/token gesendet werden

grant_type: password
username: {deine E-Mail-Adresse}
password: {dein Passwort}
client_id: {ein beliebiger String, der deine App beschreibt}
client_secret: {ein beliebiger String}

Die Werte für client_id und client_secret werden für die normale API-Nutzung nicht validiert, müssen jedoch vorhanden sein. Wir empfehlen, eine client_id zu verwenden, die deine App identifiziert. Diese Felder sind für zukünftige Authentifizierungsmethoden ohne Passwort/Benutzerkonto reserviert.

Entweder die Header origin, referrer oder companyurl müssen vorhanden sein, um das Zielkonto zu identifizieren. Der API-Zugriff kann optional auf die neutrale Adresse api.coffeecup.app anstelle einer unternehmensspezifischen Domain gerichtet werden, der Header muss jedoch das Zielkonto angeben.

cURL

curl 'https://{your-domain}.coffeecup.app/oauth2/token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -H 'origin: https://{your-domain}.coffeecup.app' 
  --data-raw 'grant_type=password&username={your-username}&password={your-passowrd}&client_id={your-app-name}&client_secret={must-be-present}'

JavaScript / Node.js Fetch

fetch("https://{your-domain}.coffeecup.app/oauth2/token", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "companyurl": "{your-domain}.coffeecup.app",
  },
  "body": "grant_type=password&username={your-username}&password={your-passowrd}&client_id={your-app-name}&client_secret={must-be-present}",
  "method": "POST",
});

Response

Die Standardantwort nach OAuth 2.0 im JSON-Format enthält das Access-Token, die Refresh-Token und die Ablaufzeit (in Sekunden — normalerweise 1 Stunde / 3600 Sekunden).

{
  "access_token": "0001112223334445556667778899aabbccddeeff",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "0001112223334445556667778899aabbccddeeff"
}

Token Refresh

Nach der anfänglichen Passwort-Authentifizierung kann das access_token über eine OAuth 2.0-Auffrischungsanfrage erneuert werden:

grant_type: refresh_token
refresh_token: {dein zuvor ausgestelltes Refresh-Token}
client_id: {ein beliebiger String, der deine App beschreibt}
client_secret: {ein beliebiger String}

cURL

curl 'https://{your-domain}.coffeecup.app/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'origin: https://{your-domain}.coffeecup.app'
  --data-raw 'grant_type=refresh_token&refresh_token={your-refresh-token}&client_id={your-app-name}&client_secret={must-be-present}'

JavaScript / Node.js Fetch

fetch("https://{your-domain}.coffeecup.app/oauth2/token", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "companyurl": "{your-domain}.coffeecup.app",
  },
  "body": "grant_type=refresh_token&refresh_token={your-refresh-token}&client_id={your-app-name}&client_secret={must-be-present}",
  "method": "POST",
});

API-Anfragen authentifizieren

Sobald ein access_token abgerufen wurde, kann das Token im authorization header als Bearer-Token verwendet werden.

Hier sind zwei Beispiele für den „me“-Endpoint, die Informationen über den aktuell angemeldeten Benutzer anzeigen:

cURL

curl 'https://{your-domain}.coffeecup.app/v1/users/me' \
  -H 'authorization: Bearer {your-access-token}'

JavaScript / Node Fetch

fetch('https://{your-domain}.coffeecup.app/v1/users/me', {
  "headers": {
    "authorization": 'Bearer {your-access-token}'
  },
});

Support

Für weitere Hilfe, Beratung und Fragen kannst du unser Support-Team über Intercom im CoffeeCup-Webbrowser-Client oder per E-Mail kontaktieren. Wir helfen dir gerne bei der Fehlerbehebung oder weisen dich auf die richtigen Feeds für deinen Anwendungsfall hin. Bitte gib bei der Kontaktaufnahme einige Hintergrundinformationen zu deinem Anwendungsfall an, damit wir dir eine maßgeschneiderte Antwort geben können.