Autenticación

Usa una clave API personal para tus propios scripts. Usa OAuth para una aplicación que actúe en nombre de otros clientes de NinjaBuy, incluidos los clientes MCP.

OAuth 2.1Copiar enlace a esta sección

Usa el flujo de código de autorización con PKCE S256. REST y MCP aceptan el mismo token de acceso OAuth de NinjaBuy. Cada token actúa en nombre de la cuenta que inició sesión y aprobó el acceso; no puedes seleccionar otra cuenta en el cuerpo de la solicitud.

Todos los endpoints de OAuth usan el origen https://www.ninjabuy.com. Rutas de descubrimiento y autorización:

Descubrimiento de OAuth · Descubrimiento del recurso MCP

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

1. Registra tu cliente en POST /api/auth/mcp/register. Un cliente público envía JSON con client_name, redirect_uris y token_endpoint_auth_method: "none". Guarda el client_id recibido.
2. Genera un state aleatorio y un code_verifier de PKCE nuevos. Calcula el code_challenge SHA-256 codificado en base64url.
3. Abre /api/auth/mcp/authorize en el navegador del usuario con response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 y scope=openid offline_access.
4. El usuario inicia sesión con su número de celular de NinjaBuy y aprueba tu aplicación. En tu callback, verifica state antes de usar el code recibido.
5. Envía un POST con codificación de formulario a /api/auth/mcp/token con grant_type=authorization_code, code, client_id, el mismo redirect_uri y code_verifier.

Envía el token de acceso obtenido en las solicitudes REST:

Authorization: Bearer YOUR_ACCESS_TOKEN

Los tokens de acceso duran 1 hora. Con offline_access, los tokens de actualización permiten renovarlos durante un máximo de 7 días. Renueva mediante el mismo endpoint de tokens con un POST con codificación de formulario que incluya grant_type=refresh_token, client_id y refresh_token. Almacena los tokens de forma segura y vuelve a iniciar sesión cuando la renovación deje de ser válida.

Si falta el token de acceso, expiró o no es válido, se devuelve 401 con un desafío de descubrimiento WWW-Authenticate. Consulta Errores.