OAuth 2.1

Für Apps, die im Namen eines Nutzers arbeiten (Zapier, n8n, Chat-Connectoren): Authorization-Code mit PKCE, Refresh-Tokens, Consent mit Organisationswahl. Für Server-zu-Server bleibt der API-Schlüssel der einfachere Weg.

Wann OAuth, wann Schlüssel

API-Schlüssel (capi_…) gehören einer Organisation und eignen sich für Skripte und Server. OAuth-Tokens gehören einem Nutzer, der im Consent eine Organisation freigibt — so verbinden Endanwender ihre eigene claritos-Organisation mit einer fremden App, ohne Schlüssel zu kopieren. Beide Wege nutzen dieselben Scopes und Endpunkte.

Authorization-Code + PKCE

Der Client leitet den Nutzer zur Autorisierung (PKCE ist Pflicht, S256), erhält nach dem Consent einen Code an seiner Redirect-URI und tauscht ihn am Token-Endpunkt gegen Access-Token (1 Stunde) und Refresh-Token (30 Tage). Vertrauliche Clients senden ihr client_secret mit; öffentliche Clients nur den code_verifier.

http

GET https://www.claritos.io/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20offline_access%20contacts:read%20invoices:write
  &state=RANDOM
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

curl

curl -X POST https://www.claritos.io/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_CALLBACK \
  -d redirect_uri=https://app.example.com/callback \
  -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET \
  -d code_verifier=CODE_VERIFIER

json

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "openid offline_access contacts:read invoices:write"
}

Consent mit Organisationswahl

Der Nutzer sieht Client und angefragte Berechtigungen und wählt die Organisation, für die der Zugriff gilt. Genau eine je Verbindung; Berechtigungen greifen nur, soweit die Rolle des Nutzers in der Organisation sie erlaubt (Mitgliedschaft wird bei jedem Aufruf geprüft). Klientendaten-Scopes brauchen zusätzlich die Freischaltung der Organisation. Seit 1.26.0 kann der Nutzer im Consent einzelne Berechtigungen abwählen; der Zugriff gilt nur für die gewählten Scopes, Klientendaten-Rechte sind standardmäßig abgewählt. Nutzer sehen ihre Freigaben im Profil unter „Verbundene Apps“ und können sie dort jederzeit widerrufen.

API aufrufen

Das Access-Token kommt wie ein Schlüssel als Bearer-Token mit. GET /me zeigt Organisation, Scopes und Limits des Tokens.

curl

curl https://www.claritos.io/api/v1/me -H "Authorization: Bearer ACCESS_TOKEN"

Token erneuern

Läuft das Access-Token ab, liefert der Token-Endpunkt mit grant_type=refresh_token ein neues Paar. Refresh-Tokens werden dabei rotiert.

curl

curl -X POST https://www.claritos.io/api/auth/oauth2/token \
  -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET

Discovery

Metadaten nach RFC 8414 (Authorization-Server) und RFC 9728 (Protected Resource) liegen an der Wurzel; die OpenID-Konfiguration zusätzlich unter dem Auth-Pfad. Clients, die Discovery unterstützen (MCP-Connectoren), brauchen nur die Basis-URL.

http

GET https://www.claritos.io/.well-known/oauth-authorization-server
GET https://www.claritos.io/.well-known/oauth-protected-resource
GET https://www.claritos.io/api/auth/.well-known/openid-configuration

Dynamic Client Registration

Clients können sich selbst registrieren (RFC 7591) — so verbinden sich claude.ai, ChatGPT und andere MCP-Clients ohne manuelles Anlegen. Registrierte Clients erscheinen im Systembereich und lassen sich dort deaktivieren.

curl

curl -X POST https://www.claritos.io/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My MCP client", "redirect_uris": ["https://client.example.com/cb"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code","refresh_token"] }'

Zapier, n8n, Make

Client im Systembereich anlegen (Redirect-URI der Plattform eintragen), client_id/client_secret dort hinterlegen, Authorization-URL /api/auth/oauth2/authorize, Token-URL /api/auth/oauth2/token, Scopes nach Bedarf (z. B. contacts:write invoices:read). PKCE aktivieren, wenn die Plattform es anbietet. Einrichtung je Plattform siehe Leitfaden „Webhooks“ → Plattformen.