Autenticação da API

Visão geral

Toda requisição às APIs do Portal do Desenvolvedor exige autenticação por Bearer Token.

O fluxo é simples:

Você executa o endpoint /auth enviando suas credenciais (username, password) e sua x-api-key.

A API responde com um Bearer Token (idToken).

Esse token é usado no cabeçalho Authorization de todas as demais chamadas.

⚠️ Você não precisa codificar nada em Base64 manualmente. O endpoint /auth cuida disso para você.

Credenciais necessárias

Para obter o token, você precisa de três informações:

Credencial	Onde vai	Descrição
`username`	corpo da chamada	Usuário fornecido pela APEX
`password`	corpo da chamada	Senha fornecida pela APEX
`x-api-key`	cabeçalho HTTP	Chave de aplicação única vinculada ao seu cadastro

⚠️ Todas as três são obrigatórias. Sem qualquer uma delas a autenticação falha.

Passo a passo

1. Obter o Bearer Token

Faça uma requisição POST para /auth enviando o x-api-key no header e suas credenciais no corpo.

Requisição:

Resposta (200 OK):

{
  "idToken": "eyJraWQiOiJ...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMi..."
}

⚠️ Use o valor de idToken como Bearer Token.

2. Usar o Bearer Token nas demais chamadas

Em qualquer outro endpoint da API, envie o idToken no cabeçalho Authorization precedido da palavra Bearer:

⚠️ O x-api-key continua sendo obrigatório em todas as requisições, mesmo após autenticar.

Exemplos de código

cURL

JavaScript (fetch)

Respostas em caso de erro

Código	Motivo	Descrição
`401 Unauthorized`	Credenciais inválidas	Usuário e/ou senha incorretos, formato do header inválido, ou foi enviado o `accessToken` no lugar do `idToken`.
`403 Forbidden`	API Key ausente ou inválida	A chave informada não é reconhecida ou não possui permissão.
`429 Too Many Requests`	Limite de requisições excedido	O cliente atingiu o limite definido no plano de uso.

Em chamadas posteriores, se o token expirar, refaça o passo 1 ou utilize o refreshToken para renovar a sessão.

Boas práticas

Não codifique credenciais em Base64 manualmente — o endpoint /auth faz isso. Se você está montando uma string usuario:senha e codificando antes de chamar, está errado.

Nunca exponha suas credenciais (usuário, senha ou API Key) em código público.

Utilize variáveis de ambiente para armazenar dados sensíveis.

Reutilize o idToken durante sua validade em vez de chamar /auth a cada requisição; use o refreshToken para renovar a sessão sem pedir credenciais novamente.

Em caso de revogação ou suspeita de uso indevido, solicite uma nova API Key imediatamente.

Visão geral#

Credenciais necessárias#

Passo a passo#

1. Obter o Bearer Token#

2. Usar o Bearer Token nas demais chamadas#

Exemplos de código#

cURL#

JavaScript (fetch)#

Respostas em caso de erro#

Boas práticas#