Autenticação com API Key

A chave tk_live_ ou tk_test_ identifica a integração e define os restaurantes, escopos, ambiente e limites de uso permitidos. Ela não é o token enviado aos endpoints de dados.

Este guia descreve o fluxo recomendado para integrações de backend. A sessão do restaurante é destinada a interfaces Takeat e fluxos interativos já autenticados; não compartilhe esse token com aplicações de terceiros.

Para implementar o ciclo completo de tokens, com validade de 900 segundos (15 minutos), rotação, concorrência e um prompt pronto para copiar, leia API Key: access e refresh tokens.

1. Criar a chave

Acesse o AI Builders com a conta do restaurante. Dê um nome à chave, escolha o ambiente e copie o valor completo quando ele aparecer.

Teste e Produção

Atualmente, o ambiente separa e identifica a credencial, mas não cria um banco de dados sandbox. Uma chave de Teste autorizada para um restaurante pode ler dados reais desse restaurante. Use o menor escopo possível e nunca trate tk_test_ como uma credencial descartável.

2. Obter os tokens

Envie um formulário application/x-www-form-urlencoded para o endpoint version-neutral de token:

export TAKEAT_API_URL="https://public-api.takeat.app"
export TAKEAT_API_KEY="tk_live_..."

curl -X POST "$TAKEAT_API_URL/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=api_key" \
  --data-urlencode "api_key=$TAKEAT_API_KEY"

Resposta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "tk_api_refresh_...",
  "scope": "menu:read products:read complements:read"
}

Esse fluxo não exige client_id nem client_secret: api_key recebe o valor completo copiado do AI Builders.

3. Chamar uma rota V1.0

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

O access token dura 15 minutos por padrão. Para renová-lo sem reenviar a API key, envie somente o refresh token atual. Ele é rotativo: descarte o valor anterior depois de cada resposta bem-sucedida.

curl -X POST "$TAKEAT_API_URL/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$TAKEAT_REFRESH_TOKEN"

Escopos disponíveis

Você pode informar scope na troca para restringir o access token a um subconjunto dos escopos da chave. Nunca é possível ampliar as permissões originais.

Limites de uso

Chaves criadas pelo restaurante usam, por padrão:

• 10 requisições por minuto;
• 500 requisições por dia, no máximo.

Os limites acompanham os access tokens emitidos pela chave. Ao receber 429, não faça retry imediato: respeite Retry-After, aplique backoff com jitter e evite polling desnecessário.

Escopo de restaurante

Uma chave criada por um restaurante no AI Builders pertence somente a ele, por isso restaurant_id é inferido. Integrações parceiras ligadas a vários restaurantes devem enviar ?restaurant_id=; a API valida se o restaurante pertence à credencial.

Revogação

Revogue a chave no AI Builders para impedir novas emissões e invalidar os access tokens e refresh tokens associados.

Segurança

• Use a API key somente no backend. Nunca a exponha em JavaScript do navegador, aplicativo mobile ou extensão distribuída.
• Não cole API key, access token ou refresh token em prompts de IA, tickets, chats, screenshots, playgrounds públicos ou logs.
• Guarde a chave em um gerenciador de segredos; use .env.local ignorado pelo Git somente no desenvolvimento.
• Persista refresh tokens criptografados e substitua o valor anterior atomicamente após cada renovação.
• Mascare Authorization, api_key e refresh_token na observabilidade.
• Em caso de vazamento, revogue a chave no AI Builders e substitua a credencial em todos os ambientes antes de retomar o tráfego.