Autenticação

Use uma chave de API pessoal para seus próprios scripts. Use OAuth para um aplicativo que atua por outros clientes da NinjaBuy, incluindo clientes MCP.

OAuth 2.1Copiar link da seção

Use o fluxo de código de autorização com PKCE S256. REST e MCP aceitam o mesmo token de acesso OAuth da NinjaBuy. Cada token atua pela conta que entrou e aprovou o acesso; você não pode selecionar outra conta no corpo da solicitação.

Todos os endpoints OAuth usam a origem https://www.ninjabuy.com. Caminhos de descoberta e autorização:

Descoberta OAuth · Descoberta do recurso MCP

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

1. Registre seu cliente em POST /api/auth/mcp/register. Um cliente público envia JSON com client_name, redirect_uris e token_endpoint_auth_method: "none". Guarde o client_id retornado.
2. Gere novos valores aleatórios de state e code_verifier do PKCE. Calcule o code_challenge SHA-256 codificado em base64url.
3. Abra /api/auth/mcp/authorize no navegador do usuário com response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 e scope=openid offline_access.
4. O usuário entra com seu número de celular da NinjaBuy e aprova seu aplicativo. No callback, verifique state antes de usar o code retornado.
5. Envie um POST codificado como formulário para /api/auth/mcp/token com grant_type=authorization_code, code, client_id, o mesmo redirect_uri e code_verifier.

Envie o token de acesso obtido nas requisições REST:

Authorization: Bearer YOUR_ACCESS_TOKEN

Os tokens de acesso duram 1 hora. Com offline_access, os tokens de atualização permitem a renovação por até 7 dias. Renove pelo mesmo endpoint de tokens usando um POST codificado como formulário com grant_type=refresh_token, client_id e refresh_token. Armazene os tokens com segurança e entre novamente quando a renovação deixar de ser válida.

Um token de acesso ausente, expirado ou inválido retorna 401 com um desafio de descoberta WWW-Authenticate. Veja Erros.