Autenticação e permissões

As chamadas protegidas usam um token bearer de curta duração, obtido pelo fluxo OAuth 2.0 client credentials. As credenciais da chave de API são usadas somente para obter esse token; não as envie nos demais endpoints.

Gere e envie o token

Chame POST /api/auth/token/ com o corpo application/x-www-form-urlencoded contendo grant_type=client_credentials, e autentique o cliente com HTTP Basic: cabeçalho Authorization: Basic <base64(client_id:client_secret)>.

A resposta inclui access_token, token_type (Bearer), expires_in e scope. Em cada chamada protegida, envie o token no cabeçalho:

Authorization: Bearer <access_token>

O token identifica a loja (tenant) e o ambiente (environment) associados à chave. Esses valores não são selecionados por parâmetros da chamada. Veja Primeiros passos para um exemplo completo.

Permissões

O acesso de uma chave é delimitado pela loja, pelo ambiente e pelos escopos que foram concedidos a ela. O campo scope da resposta de POST /api/auth/token/ mostra os escopos concedidos ao token, separados por espaço. Consulte o guia Escopos de acesso para ver os recursos e endpoints correspondentes.

Por padrão, o token recebe todos os escopos da chave. Para um token mais restrito, envie o parâmetro scope com um subconjunto deles (ex.: scope=store menu); pedir um escopo que a chave não possui resulta em 400 com error igual a invalid_scope. Use credenciais emitidas para a loja e o ambiente que a integração deve consultar. Se precisar de acesso a outro recurso, loja ou ambiente, peça ao responsável pela gestão das chaves que ajuste a configuração.

Expiração e renovação

Os tokens expiram. Confira expires_in na resposta de emissão e solicite outro token com o mesmo client_id e client_secret antes de fazer novas chamadas após a expiração. O endpoint não emite um token de renovação separado.

O valor padrão configurado é de 900 segundos (15 minutos), mas a resposta de POST /api/auth/token/ é a referência para a validade efetiva naquele ambiente.

Revogação e armazenamento seguro

• Proteja o client_secret como uma senha: não o coloque no navegador, no aplicativo móvel, no repositório de código ou em registros de aplicação.
• Armazene credenciais e tokens em um cofre de segredos e use HTTPS.
• A revogação da chave ou da sessão invalida imediatamente os tokens e impede a emissão de novos tokens para a chave revogada.
• Um token bearer ausente, inválido ou expirado resulta em 401, com o cabeçalho WWW-Authenticate: Bearer ..., error="invalid_token"; emita um token novo e repita a chamada protegida uma vez.

Erros do endpoint de token

Os erros de POST /api/auth/token/ seguem a RFC 6749 §5.2: o corpo traz error e error_description, além dos campos code e detail usados no resto da API, com os mesmos valores.