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

1. Receba o clientId e clientSecret da equipe da Carrot API.
2. Solicite um token de acesso no endpoint de autenticação utilizando Basic Authentication.
3. 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 unauthorized: token bearer inválido, expirado ou malformado.
• 403 restrictedResource: token válido sem permissão para o recurso ou ambiente alvo.

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