MCP-Autorisierung: OAuth 2.1-Anmeldung
Diese Seite behandelt die Autorisierung für die MCP-Server auf der Casafari API- und MCP-Plattform: wie ein MCP-Client ein Zugriffstoken erhält und dabei dem Autorisierungsfluss des Model Context Protocol folgt (OAuth 2.1 mit PKCE und Metadaten geschützter Ressourcen). Die REST-API der Plattform benötigt keinen OAuth-Fluss: Ein Plattform-API-Schlüssel aus der Konsole signiert jeden Aufruf, siehe Plattform-API-Schlüssel. Die bestehende REST-API unter api.casafari.com (für Vertragskunden) nutzt eine abweichende Anmeldung mit E-Mail, Passwort und Bearer-Token: siehe die bestehende API.
Es gibt einen Autorisierungsserver. Jeder MCP-Server – der Hauptserver für alle Produkte (https://platform.casafari.com/mcp) sowie die individuellen Server der einzelnen Produkte – ist eine eigene geschützte Ressource: Ein Zugriffstoken funktioniert nur auf dem Server, für den es ausgestellt wurde. Ein Zugriffstoken agiert im Namen des Plattform-Accounts einer Person; der Plan des Accounts, die Tokens und die Produkte bestimmen, was mit einem Aufruf möglich ist. Die maßgebliche, für Agents bestimmte Version dieser Seite ist die auth.md der Plattform. mcp.casafari.com ist das Legacy-Gateway, das weiterhin antwortet, aber auf https://platform.casafari.com/mcp/<product> umgestellt wird.
Discovery
Eine Anfrage ohne Token antwortet mit 401 und einem Header WWW-Authenticate: Bearer resource_metadata="...". Für die Casafari Platform (https://platform.casafari.com/mcp) verweist dieser auf:
- Die Metadaten der geschützten Ressource, https://platform.casafari.com/.well-known/oauth-protected-resource/mcp. Lesen Sie
resource,authorization_serversundscopes_supportedaus. Übermitteln Sieresourceals Parameterresourcebei jeder Autorisierungs- und Token-Anfrage: Die Tokens sind als Audience an diese gebunden. - Die Metadaten des Autorisierungsservers, https://platform.casafari.com/.well-known/oauth-authorization-server, für die Endpunkte zur Registrierung, Autorisierung und Token-Ausgabe.
Anmeldung im Namen einer Person
- Registrieren (einmalig): Verwenden Sie die URL Ihres Client-ID-Metadatendokuments als
client_idoder registrieren Sie sich mittels dynamischer Client-Registrierung (RFC 7591) als öffentlicher Client (token_endpoint_auth_methodnone, Grant-Typenauthorization_codeundrefresh_token). Bewahren Sie dieclient_idauf. - Autorisieren: Leiten Sie die Person zum Autorisierungsendpunkt mit PKCE (
S256),stateundresourceweiter.scopeist optional (Standard: jeder Scope der Ressource). Die Person meldet sich an oder erstellt einen Account, akzeptiert die Plattform-Nutzungsbedingungen und autorisiert Ihren Client. - Code austauschen am Token-Endpunkt unter Verwendung des PKCE-Verifiers. Zugriffstokens sind 15 Minuten gültig (
expires_in900) und werden zusammen mit einem Refresh-Token ausgegeben. - Server aufrufen mit
Authorization: Bearer <access_token>. - Aktualisieren mit
grant_type=refresh_token: Jede Aktualisierung gibt ein neues Paar zurück; behalten Sie nur das neueste. Die erneute Verwendung eines bereits genutzten Refresh-Tokens widerruft die Berechtigung, woraufhin die Person Ihren Client erneut autorisieren muss.
Für den eigenen Server eines Produkts autorisieren Sie sich erneut mit dessen resource: ein Account, separate Tokens.
Agents ohne Person
Ein Client, der sich selbst registriert hat, kann client_credentials nicht verwenden. Für Aufgaben, die unbeaufsichtigt ausgeführt werden, erstellt die Person einen API-Schlüssel (cf_sk_..., wird sowohl bei MCP als auch bei REST als Authorization: Bearer übertragen) oder einen vertraulichen OAuth-Client in der Konsole unter https://platform.casafari.com/console und stellt diesen dem Agent zur Verfügung. Ein vertraulicher OAuth-Client funktioniert über REST: Fordern Sie ein Token am Endpunkt https://platform.casafari.com/oauth/token mit dem Grant-Typ „Client Credentials“ an, wobei resource auf die URL des Produkts gesetzt wird, z. B. https://platform.casafari.com/v1/area-insights. Dieses Token ist 15 Minuten gültig und enthält kein Refresh-Token; fordern Sie bei Ablauf ein neues an. Ein API-Schlüssel erfordert diesen Austausch nicht.
Fehler
Jeder Fehler ist vom Typ application/problem+json, dessen type auf eine Seite unter https://platform.casafari.com/errors/<code> verweist.
| Status | Bedeutung | Vorgehensweise |
|---|---|---|
401 invalid_credential | Token oder Schlüssel fehlt, wurde widerrufen, ist abgelaufen oder gehört zu einer anderen Ressource | Aktualisieren; falls dies fehlschlägt, erneut autorisieren |
402 payment_required | Die Tokens des Accounts sind aufgebraucht | Füllen Sie Tokens unter upgrade_url auf (der Inhaber oder ein Mitglied mit Abrechnungsrechten zahlt); prüfen Sie den Zahlungslink und versuchen Sie es erneut |
403 not_entitled, insufficient_scope | Der Plan oder die Scopes des Zugriffstokens decken den Aufruf nicht ab | Nicht erneut versuchen |
429 | Ein Anfrage-Limit oder ein Nutzungszeitraum wurde erreicht | Warten Sie gemäß Retry-After (Limits) |
5xx | Vorübergehender Fehler | Erneuter Versuch mit exponentiellem Backoff |