Autenticação

A Carrot API utiliza OAuth 2.0 com credenciais de cliente e tokens bearer. Não há etapa de login de usuário. As integrações se autenticam com um clientId e clientSecret.

Fluxo de autenticação

Receba o clientId e clientSecret da equipe da Carrot API.
Solicite um token de acesso no endpoint de autenticação utilizando Basic Authentication.
Utilize o token bearer retornado no cabeçalho Authorization nas requisições à API.

curl --request POST \
  --url https://auth.api.carrot.eco/oauth2/token \
  --header 'Authorization: Basic <clientId:clientSecret em base64>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api.carrot.eco/main-scope'

Ciclo de vida do token

A duração máxima do access_token é atualmente de 1 hora.
expires_in é retornado na resposta do endpoint de token e deve ser tratado como dado de runtime fornecido pela API (não codificado fixo na sua integração).
Tokens de atualização (refresh tokens) não são utilizados neste fluxo.
Solicite um novo token antes da expiração para evitar falhas nas requisições.

Formato da resposta do token

Resposta típica de sucesso:

{
  "access_token": "<jwt-ou-token-opaco>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.carrot.eco/main-scope"
}

Utilizando tokens bearer

Envie seu token em cada requisição:

Authorization: Bearer <access_token>

Comportamento por ambiente

O ambiente é controlado pelas credenciais, não pela URL.

Credenciais de teste operam apenas em dados de teste.
Credenciais de produção operam apenas em dados de produção.
Um token de teste não pode modificar documentos de produção, e o inverso também é verdadeiro.

Consulte Ambientes para orientações operacionais.

Erros comuns de autenticação

401 — o token não pôde ser decodificado: sem header Authorization, ou um valor bearer que não é um JWT decodificável. O corpo é {"message":"Unauthorized"}, sem campo code.
403 (autorizador de borda) — o token foi decodificado mas rejeitado: expirado, assinatura inválida, esquema diferente de Bearer, escopo não permitido ou issuer divergente. O corpo é {"message":"<motivo>"}, por exemplo {"message":"Authorization token expired"}. Não há envelope errors[].
403 (RESTRICTED_RESOURCE_ERROR) — token válido sem permissão para o recurso alvo, incluindo uma credencial de teste acessando dados de produção ou o inverso. O corpo é o envelope errors[] padrão descrito em Erros.

Renove no 403, não no 401

Um token expirado nunca produz 401 — ele é rejeitado na borda como 403, então uma lógica de renovação baseada em 401 nunca será acionada. Renove apenas quando o corpo vindo do gateway identificar expiração ({"message":"Authorization token expired"}). As outras causas de 403 — assinatura inválida, escopo ou issuer errado, RESTRICTED_RESOURCE_ERROR — não são resolvidas por um token novo, e retentar depois de renovar apenas cria um laço.

Ambientes · Início Rápido · Tratamento de Erros