API Key: access e refresh tokens

Este guia mostra como manter uma integração de backend autenticada com uma API key criada no AI Builders. O access token expira em 900 segundos (15 minutos) por padrão. O refresh token permite obter outro par de tokens sem reenviar a API key a cada renovação.

Se você já conhece o fluxo, vá direto ao prompt para implementar com um agente. Para criar a chave e escolher seus escopos, leia Autenticação com API Key.

Qual credencial usar em cada etapa?

A API responde em snake_case: access_token, refresh_token e expires_in. Seu código pode usar accessToken e refreshToken internamente, mas deve preservar os nomes originais nos formulários e na leitura do JSON.

1. Troque a API key por tokens

Faça a troca no backend, com Content-Type: application/x-www-form-urlencoded. O endpoint é /oauth/token, sem /v1. Os exemplos assumem variáveis preenchidas pelo seu ambiente seguro; não cole segredos reais no código, no terminal compartilhado ou no prompt do agente.

curl --request POST "https://public-api.takeat.app/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=api_key" \
  --data-urlencode "api_key=$TAKEAT_API_KEY"

Opcionalmente, envie scope com escopos separados por espaços para restringir as permissões aos recursos necessários. Não é possível ampliar os escopos da chave. Não envie Authorization nesta requisição.

Resposta de sucesso, com valores fictícios:

{
  "access_token": "ACCESS_TOKEN_FICTICIO",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "tk_api_refresh_EXEMPLO",
  "scope": "menu:read products:read"
}

Verifique o status HTTP e valide os campos antes de persistir a resposta. Armazene o par de tokens e sua expiração no backend, associado à integração, ao ambiente e ao contexto de restaurante autorizado. Não devolva esses tokens ao navegador.

2. Use o access token por até 900 segundos

curl "https://public-api.takeat.app/v1/menu?channel=delivery" \
  --header "Authorization: Bearer $TAKEAT_ACCESS_TOKEN"

Essa chamada exige menu:read. Uma chave de um único restaurante permite que a API infira restaurant_id. Se uma chave de parceiro autoriza vários restaurantes, informe ?restaurant_id= nas rotas de dados; a API valida esse vínculo. Nunca use a API key ou o refresh token como Bearer das rotas de dados.

Reutilize o access token entre chamadas. Não faça uma nova troca de API key para cada requisição. Embora o padrão seja 900 segundos, calcule a validade com o expires_in recebido em cada resposta, pois ele representa o prazo retornado pelo servidor.

expiresAt = requestStartedAt + expires_in * 1000
refreshAt = expiresAt - 60_000

Os horários acima estão em milissegundos. Registre requestStartedAt antes de enviar a troca ou renovação e use uma margem de 60 segundos para latência e diferenças de relógio. Com expires_in=900, a aplicação começa a renovar após 840 segundos (14 minutos). Confira esse prazo antes de cada chamada; um timer sozinho não cobre reinícios ou processos que ficaram suspensos.

3. Renove com o refresh token atual

Quando chegar a hora de renovar, envie somente os dois campos abaixo. Não envie a API key, client_id, client_secret, scope nem Authorization.

curl --request POST "https://public-api.takeat.app/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$TAKEAT_REFRESH_TOKEN"

A resposta tem o mesmo formato da primeira troca, mas contém outro access_token e outro refresh_token, além de expires_in, token_type e scope. Substitua o par antigo e recalcule a expiração em uma única gravação atômica. Só libere o novo access token para chamadas depois de salvar o novo refresh token com sucesso.

O prazo de 900 segundos é do access token, não do refresh token. Na configuração padrão, o refresh expira após 30 dias sem uso; sua família tem limite absoluto de 90 dias desde a primeira troca. Cada renovação reinicia o prazo de inatividade, sem ultrapassar o limite absoluto. Esses prazos podem ser configurados no servidor e não são retornados como expires_in: trate invalid_grant mesmo que seu controle local considere o refresh válido.

Rotação e chamadas simultâneas

Cada refresh token só pode ser usado uma vez. Reutilizar um token consumido revoga sua família de refresh tokens e invalida access tokens associados à chave. Por isso, não basta salvar a última resposta recebida.

1. Coordene uma única renovação por contexto de credenciais. No mesmo processo, as chamadas aguardam a mesma promessa de renovação.
2. Se houver várias instâncias ou workers, use coordenação compartilhada que impeça duas chamadas de refresh com o mesmo token. Um lock apenas em memória não é suficiente.
3. Depois de obter o lock, releia o estado persistido: outra instância pode já ter renovado. Nesse caso, use o par novo sem repetir a renovação.
4. Salve o novo par e a expiração atomicamente, libere o lock e retome as chamadas que estavam aguardando.

4. Trate falhas sem criar loops

Não repita automaticamente escritas (POST, PUT, PATCH) quando o resultado for incerto. Verifique a operação e a segurança da repetição; não presuma que um header de idempotência é suportado se o contrato não o documenta.

Para recuperar uma integração após expiração do refresh, confirme que a API key continua válida e faça uma nova troca com grant_type=api_key de forma coordenada. Se houver suspeita de reutilização ou vazamento, investigue e revogue/substitua a chave antes de reconectar. Não use a nova troca em loop como forma de contornar uma revogação. A revogação da chave no AI Builders impede novas emissões e invalida os tokens associados.

Segurança e persistência

• Mantenha a API key em um gerenciador de segredos, disponível somente no backend.
• Persista refresh tokens criptografados e controle o acesso ao estado de tokens; se persistir access tokens, proteja-os também. Recupere o estado após reinícios.
• Separe credenciais e locks por integração/ambiente; não compartilhe tokens entre restaurantes sem autorização da mesma chave.
• Nunca coloque segredos em localStorage, código de frontend, URLs, Git, logs, analytics, mensagens de erro ou prompts. Mascare Authorization, api_key, access_token e refresh_token na observabilidade.
• Uma chave tk_test_ não cria um sandbox: ela pode acessar dados reais. Faça testes automatizados com mocks e valores fictícios.

Prompt para implementar com um agente

Copie o bloco abaixo para o agente que trabalha no seu projeto. Acrescente somente o objetivo da integração e as operações desejadas, sem credenciais reais. O prompt implementa este fluxo de API key; para um aplicativo instalável por vários restaurantes, siga o guia OAuth.

Implemente no backend deste projeto a integração com a Nova API V1.0 da
Takeat usando API key, access token e refresh token. Inspecione a arquitetura
e siga as convenções e os testes existentes, preservando alterações alheias.
O escopo é a autenticação e o cliente HTTP para as operações solicitadas;
não crie funcionalidades de negócio nem altere o fluxo para OAuth com PKCE.

Leia as fontes oficiais antes de implementar:
https://docs.takeat.app/llms.txt
https://docs.takeat.app/md/v1/autenticacao.md
https://docs.takeat.app/md/v1/api-key-tokens.md
https://docs.takeat.app/openapi-v1.yaml
Localize também o contrato .md de cada operação utilizada. Se houver
divergências ou algo não documentado, sinalize; não invente campos ou rotas.

Contrato de autenticação:
1. Base da API: https://public-api.takeat.app. O endpoint de tokens é
   POST /oauth/token, sem /v1, com application/x-www-form-urlencoded.
2. Primeira troca: grant_type=api_key e api_key=valor de TAKEAT_API_KEY,
   lido apenas no backend. scope é opcional e só pode restringir permissões.
   Não envie client_id, client_secret, Basic Auth ou Authorization.
   Não use client_credentials: esse grant não devolve refresh token.
3. Valide status e resposta: access_token, refresh_token, token_type=Bearer,
   expires_in e scope. Os campos HTTP são snake_case, mesmo que as variáveis
   internas sejam accessToken e refreshToken.
4. O access token expira em 900 segundos (15 minutos) por padrão. Use o
   expires_in retornado em cada troca, convertido de segundos para
   milissegundos, e o instante anterior ao envio da requisição para calcular
   expiresAt. Renove com margem de 60 segundos e confira o prazo antes de
   cada chamada. Reutilize o token; não troque a API key a cada requisição.
5. Nas rotas de dados /v1/*, envie Authorization: Bearer <access_token>.
   Nunca use API key ou refresh token como Bearer. Respeite escopos e o
   restaurante autorizado; envie restaurant_id apenas conforme o contrato
   e o vínculo da chave. Não use login/sessão de restaurante de terceiros.
6. Renovação: POST /oauth/token com apenas grant_type=refresh_token e
   refresh_token=valor atual, como formulário. Não envie api_key, client_id,
   client_secret, scope ou Authorization nessa chamada.
7. Cada refresh é de uso único e retorna outro par de tokens. Salve ambos,
   scope e a nova expiração atomicamente antes de liberar chamadas em espera.
   Persista com segurança para sobreviver a reinícios. O refresh não expira
   em 900 segundos: o padrão é 30 dias sem uso e 90 dias absolutos por família;
   isso não dispensa tratar expiração/revogação retornadas pelo servidor.

Concorrência e recuperação:
- Implemente uma única renovação em andamento por contexto de credenciais.
  No mesmo processo, compartilhe a promessa; com vários workers/instâncias,
  use coordenação compartilhada e releia os tokens depois de adquirir o lock.
  Nunca envie duas renovações com o mesmo refresh token. Reutilização revoga
  a família e invalida access tokens associados à chave.
- Em timeout, falha de rede, 5xx ou erro de persistência após um refresh,
  não repita cegamente o token antigo: ele pode ter sido consumido. Releia o
  estado e, se não houver novo par, pare e exponha recuperação controlada.
- Em 401 de dados, confira se outra chamada já renovou; caso contrário,
  coordene no máximo uma renovação. Repita a chamada original no máximo uma
  vez e somente se for seguro. Um segundo 401 deve encerrar a tentativa.
- Em invalid_grant, pare o ciclo de refresh. Uma nova troca com API key
  válida deve ser controlada, após verificar a causa; não contorne revogação
  ou suspeita de vazamento. Trate invalid_client como falha de credencial.
- Não renove por 403; verifique escopos/restaurante. Em 429, respeite
  Retry-After quando presente e use backoff com jitter e tentativas limitadas.
  Não repita escritas com resultado incerto nem invente idempotência.

Segurança e entrega:
- Não peça, leia, imprima ou cole segredos reais. Não abra arquivos .env.
  Use apenas nomes de variáveis e placeholders em .env.example; a configuração
  real será feita fora do chat. Nunca exponha tokens ao navegador, localStorage,
  URLs, Git, logs, analytics ou mensagens de erro. Criptografe tokens
  persistidos e mascare headers e campos sensíveis.
- Isole estado e locks por integração/ambiente/contexto autorizado. Não
  execute chamadas reais à Takeat; tk_test_ também pode acessar dados reais.
- Teste com HTTP simulado, relógio controlado e tokens fictícios: formulário
  inicial, Bearer correto, reaproveitamento antes da expiração, margem de
  renovação, rotação/persistência, reinício, concorrência, timeout ambíguo,
  invalid_grant, 401 sem loop, 403 sem refresh, 429 e segurança de escritas.
- Implemente, execute as verificações disponíveis e entregue um resumo dos
  arquivos alterados, configuração necessária, testes executados e limites
  de verificação. Não declare integração em produção validada por mocks.

Próximas leituras

• Criar a chave e escolher escopos
• Referência das requisições
• OAuth para aplicativos instaláveis
• Documentação para agentes e MCP