Authentifizierung

Verwende einen persönlichen API-Schlüssel für deine eigenen Skripte. Verwende OAuth für eine Anwendung, die für andere NinjaBuy-Kunden handelt, einschließlich MCP-Clients.

OAuth 2.1Abschnittslink kopieren

Verwende den Authorization-Code-Flow mit PKCE S256. REST und MCP akzeptieren dasselbe NinjaBuy-OAuth-Zugriffstoken. Jedes Token handelt für das Konto, das sich angemeldet und den Zugriff genehmigt hat. Im Anfragekörper kannst du kein anderes Konto auswählen.

Alle OAuth-Endpunkte verwenden den Ursprung https://www.ninjabuy.com. Pfade für Discovery und Autorisierung:

OAuth-Discovery · MCP-Ressourcen-Discovery

POST /api/auth/mcp/register
GET  /api/auth/mcp/authorize
POST /api/auth/mcp/token

1. Registriere deinen Client über POST /api/auth/mcp/register. Ein öffentlicher Client sendet JSON mit client_name, redirect_uris und token_endpoint_auth_method: "none". Bewahre die zurückgegebene client_id auf.
2. Erzeuge einen neuen zufälligen state und PKCE-code_verifier. Berechne daraus den base64url-codierten SHA-256-code_challenge.
3. Öffne /api/auth/mcp/authorize im Browser des Nutzers mit response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 und scope=openid offline_access.
4. Der Nutzer meldet sich mit seiner NinjaBuy-Telefonnummer an und genehmigt deine Anwendung. Prüfe an deinem Callback state, bevor du den zurückgegebenen code verwendest.
5. Sende einen formularcodierten POST an /api/auth/mcp/token mit grant_type=authorization_code, code, client_id, derselben redirect_uri und code_verifier.

Sende das erhaltene Zugriffstoken bei REST-Anfragen mit:

Authorization: Bearer YOUR_ACCESS_TOKEN

Zugriffstoken gelten 1 Stunde. Mit offline_access ermöglichen Refresh-Token die Erneuerung für bis zu 7 Tage. Erneuere am selben Token-Endpunkt mit einem formularcodierten POST mit grant_type=refresh_token, client_id und refresh_token. Speichere Token sicher und melde dich erneut an, wenn die Erneuerung nicht mehr gültig ist.

Ein fehlendes, abgelaufenes oder ungültiges Zugriffstoken ergibt 401 mit einem WWW-Authenticate-Verweis auf die Metadaten. Siehe Fehler.