Autenticação

A API do Mercury usa autenticação por token Bearer: sua integração se autentica como uma aplicação (não como um usuário final), trocando um par clientId / clientSecret por um token de acesso. Esse token é enviado em cada chamada subsequente e carrega as permissões que determinam quais operações sua integração pode executar.

Obter credenciais

O acesso à API é feito com um par clientId / clientSecret. Essas credenciais precisam ser cadastradas antes do primeiro uso — gere-as no Painel de Admin, em Integrações → API Tokens. Ao criar um token você obtém:

clientId — identificador público da sua integração. Pode ser exposto em logs e usado para identificar a origem das chamadas.

clientSecret — segredo da sua integração. Trate-o como uma senha: não versione em repositório, não exponha no front-end, não compartilhe por canais inseguros, e rotacione imediatamente se houver suspeita de vazamento (revogando o token comprometido e gerando um novo).

Cada par de credenciais é válido em um único ambiente (produção ou sandbox) — veja Ambientes para detalhes.

Fluxo de autenticação

Obtenha o token em POST /v1/token, enviando clientId e clientSecret:

Resposta (exemplo):

{
  "access_token": "eyJhbGciOiJFUzI1NiI..."
}

Se clientId/clientSecret forem inválidos ou o token estiver revogado, o endpoint responde 401 Unauthorized.

O endpoint POST /v1/token é público (não exige permissão) — é o ponto de entrada do fluxo.

Envie o token em toda chamada subsequente, no header Authorization:

Authorization: Bearer <access_token>

O token é válido por 15 minutos. Quando expirar, uma chamada autenticada passa a responder 401 Unauthorized — nesse caso, repita o passo 1 para obter um novo token. Não é necessário (nem recomendado) armazenar o token além da sua janela de validade: solicite um novo sob demanda, e trate a renovação como parte natural do fluxo de chamadas da sua integração, não como um caso de erro excepcional.

Permissões

Uma permissão autoriza o token a executar um conjunto de operações sobre um recurso. Cada token carrega as permissões concedidas às suas credenciais, e cada operação da API exige uma permissão específica — consulte a referência completa e veja a permissão exigida no endpoint desejado.

Como o acesso é verificado

Token ausente ou inválido → resposta 401 Unauthorized.

Token válido, mas sem a permissão exigida pela operação → resposta 403 Forbidden.

Se sua integração receber 403 em uma chamada que espera funcionar, o token não tem a permissão necessária — confira a permissão exigida pelo endpoint na referência completa e, se necessário, solicite o ajuste de permissões conforme a seção abaixo.

Como as permissões são concedidas

Por padrão, todo token criado pelo Painel de Admin recebe acesso a todas as permissões disponíveis. Isso cobre a maioria das integrações, que consomem múltiplos recursos da API.

Se sua integração precisa de um token restrito a permissões específicas (por exemplo, por política de segurança interna ou princípio de menor privilégio), isso não é feito por autoatendimento no Painel de Admin — é necessário abrir um chamado solicitando as permissões desejadas para o token. O time responsável avalia e aplica a restrição diretamente nas credenciais.

Próximos passos

Ambientes — base URLs por ambiente.

Obter credenciais#

Fluxo de autenticação#

Permissões#

Como o acesso é verificado#