Autenticazione

Usa una chiave API personale per i tuoi script. Usa OAuth per un’applicazione che agisce per altri clienti NinjaBuy, inclusi i client MCP.

OAuth 2.1Copia link alla sezione

Usa il flusso del codice di autorizzazione con PKCE S256. REST e MCP accettano lo stesso token di accesso OAuth NinjaBuy. Ogni token agisce per l'account che ha effettuato l'accesso e approvato l'autorizzazione; non puoi selezionare un altro account nel corpo della richiesta.

Tutti gli endpoint OAuth usano l’origine https://www.ninjabuy.com. Percorsi di discovery e autorizzazione:

Discovery OAuth · Discovery della risorsa MCP

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

1. Registra il tuo client con POST /api/auth/mcp/register. Un client pubblico invia JSON con client_name, redirect_uris e token_endpoint_auth_method: "none". Conserva il client_id restituito.
2. Genera nuovi valori casuali per state e code_verifier di PKCE. Calcola il code_challenge SHA-256 codificato in base64url.
3. Apri /api/auth/mcp/authorize nel browser dell'utente con response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 e scope=openid offline_access.
4. L'utente accede con il proprio numero di telefono NinjaBuy e approva la tua applicazione. Nel callback, verifica state prima di usare il code restituito.
5. Invia un POST codificato come modulo a /api/auth/mcp/token con grant_type=authorization_code, code, client_id, lo stesso redirect_uri e code_verifier.

Invia il token di accesso ottenuto nelle richieste REST:

Authorization: Bearer YOUR_ACCESS_TOKEN

I token di accesso durano 1 ora. Con offline_access, i token di aggiornamento consentono il rinnovo per un massimo di 7 giorni. Usa lo stesso endpoint dei token con un POST codificato come modulo contenente grant_type=refresh_token, client_id e refresh_token. Conserva i token in modo sicuro e accedi di nuovo quando il rinnovo non è più valido.

Un token di accesso assente, scaduto o non valido restituisce 401 con una richiesta di autenticazione WWW-Authenticate che fornisce i metadati di discovery. Consulta Errori.