Authentication

Como as API keys funcionam na Routal — onde gerá-las, como desativá-las e como mantê-las seguras.

A API da Routal usa API keys para autenticar cada requisição. As chaves têm escopo de uma única organização e concedem as mesmas permissões do usuário que as criou.

Como as chaves são usadas

Passe sua chave como query parameter private_key em cada requisição:

curl -G 'https://api.routal.com/v2/vehicles' \
  --data-urlencode 'private_key=YOUR_KEY'

Para métodos que aceitam body (POST, PUT), mantenha private_key na query string e ponha o payload no body:

curl -X POST 'https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "Hello"}'

A API não aceita chaves no header Authorization hoje.

Formato da chave

As API keys são strings alfanuméricos aleatórios com prefixo api_key_ (ex.: api_key_xY7…32 chars). Trate o string inteiro como o segredo — não há uma "parte secreta" separada para extrair.

Gerar e gerenciar chaves

Crie, etiquete, desative e exclua chaves no dashboard do planner:

planner.routal.com/h/settings/developers/api-keys

Cada chave tem:

Um label que você escolhe (ex.: staging-integration, analytics-readonly) — apenas para seu próprio controle.
Um flag active — quando false a chave é rejeitada na auth. Útil para revogar temporariamente sem excluir.
Um timestamp created at.

Não há timestamp last_used_at hoje — do dashboard você não consegue saber quando (ou se) uma chave específica foi usada por último.

Você pode ter múltiplas chaves ativas ao mesmo tempo por organização, o que torna a rotação indolor.

Segurança

Trate a chave como uma senha. Qualquer um com a chave pode ler e modificar cada plan, route, stop e vehicle da sua organização (entre os projetos aos quais o usuário criador tem acesso).
Nunca commite chaves em um repositório. Use variáveis de ambiente (process.env.ROUTAL_API_KEY) ou um secret manager (1Password, Doppler, AWS Secrets Manager, Vault).
Nunca coloque uma chave em uma URL que termina em logs. A maioria dos logs de servidor e HTTP intermediaries capturam URLs inteiras, incluindo query strings. Onde possível, logue apenas o path e redacte a query string antes de persistir. Esse é o maior risco prático da auth via query string.
Código no browser é proibido. Uma chave enviada ao browser é uma chave pública. Se precisar chamar a API do browser, faça proxy pelo seu próprio backend.

Rotação

Rotacione chaves em cadência regular (a cada 90 dias é um default razoável) e imediatamente se suspeitar de exposição.

Padrão recomendado:

Gere uma chave nova no dashboard. Mantenha a existente ativa.
Faça deploy dos seus serviços com a nova chave.
Quando estiver confiante de que nada ainda usa a antiga (janela de deploy + margem), defina o flag active da antiga para false no dashboard. Se algo ainda a estiver chamando, você verá falhas de auth — pode reativá-la instantaneamente.
Depois de outra janela sem reativações, exclua a chave antiga permanentemente.

Esse swap zero-downtime funciona porque a Routal suporta múltiplas chaves ativas simultaneamente por organização.

As API keys hoje têm escopo de organização: podem ler e modificar qualquer recurso ao qual o usuário criador tem acesso. Não há scoping per-key (read-only vs. read-write, scoping por projeto, IP allowlist, etc.).

Se sua integração só precisa de acesso de leitura, isole-a atrás da sua própria camada de serviço.

Scopes granulares estão no roadmap. Se você tem um caso de uso concreto, fale conosco.

E agora

Quickstart — faça sua primeira chamada autenticada.
Errors — o que acontece quando uma chave está ausente, mal formada ou desativada. (Spoiler: toda falha de auth com API key aparece hoje como highway.apiKey.error.not_found.)