Autenticação

A autenticação tem dois passos. Você guarda uma chave de API de vida longa e a troca, a cada uso, por um token que vale dois minutos. Só o token abre as rotas de leitura.

Chave de API

A chave é a credencial de máquina da sua integração.

Formato. Hoje começa com adv_, um prefixo anterior ao nome owiew que ainda está em uso, seguido de caracteres aleatórios. O prefixo existe para que varredores de segredo reconheçam a chave se ela for commitada por engano. Não escreva código que dependa dele: ele pode mudar.
Aparece uma vez. O servidor guarda só uma impressão digital da chave. Se você perder o valor, não há como recuperá-lo: crie outra chave e revogue a antiga.
Escopo por cliente. Uma chave pertence a um único cliente. Ela nunca enxerga dados de outro.
Escopo por conta de anúncio. A chave pode valer para todas as contas do cliente ou apenas para uma lista delas. Veja Permissões e escopo.
Só leitura. Uma chave aceita apenas papéis de leitura. A restrição é conferida na criação, no armazenamento e de novo na emissão de cada token. Nenhuma chave consegue executar ações na plataforma de anúncio.
Prazo obrigatório. Toda chave expira. O prazo padrão é de 90 dias e o máximo é de 365. Não existe chave sem validade. Quando ela vence, a troca por token passa a responder 401 e a integração para, de forma visível, em vez de deixar uma porta esquecida aberta.
Revogação. Quem administra o cliente pode revogar uma chave a qualquer momento. A revogação vale a partir da próxima troca por token. Um token já emitido continua válido pelo tempo que lhe resta, no máximo dois minutos.

Por que não existe usuário de serviço

O login de pessoas na owiew exige um segundo fator, e um programa não consegue ler um código no e-mail. A saída errada seria isentar uma “conta de serviço” desse segundo fator. Ela criaria a única conta sem segundo fator do sistema, com leitura de tudo, que é exatamente a conta que um atacante procura.

A chave de API é a alternativa: não é uma pessoa, não faz login, não abre o painel, é revogável, tem escopo e prazo, e só lê. Por isso não precisa de segundo fator e não substitui nenhuma conta de usuário.

Como obter uma chave

Hoje a chave é emitida a pedido. Peça ao suporte da owiew, informando:

o nome da integração (aparece na lista de chaves e facilita revogar a certa);
o papel de leitura desejado;
as contas de anúncio que a chave deve enxergar, se quiser limitar;
o prazo, em dias (padrão 90, máximo 365).

Trocar a chave por um token

POST /v1/token, com a chave no cabeçalho Authorization:

curl -sS -X POST "$OWIEW_API_URL/v1/token" \
  -H "Authorization: Bearer $OWIEW_API_KEY"

A chave vai no cabeçalho, nunca no corpo nem na URL. Corpo de requisição aparece em log de aplicação com frequência, e a URL aparece em log de proxy e em histórico de navegador.

A resposta traz o token e o escopo dele (valores de exemplo):

{
  "access_token": "TOKEN_DE_EXEMPLO",
  "expires_at": "2026-10-28T12:02:00Z",
  "tenant_id": "ID_DO_CLIENTE_EXEMPLO",
  "tenant_slug": "cliente-exemplo",
  "tenant_name": "Cliente Exemplo",
  "role": "viewer",
  "permissions": ["insights.read", "account.read"],
  "accounts": ["*"],
  "display_currency": "BRL"
}

Campo	Significado
`access_token`	O token. Vai no cabeçalho das leituras.
`expires_at`	Quando o token deixa de valer (UTC).
`tenant_id`	O cliente da chave. Vai no caminho das rotas de leitura. Você não o escolhe.
`role`, `permissions`	O papel e as permissões que o token concede.
`accounts`	As contas de anúncio visíveis. `["*"]` significa todas do cliente.
`display_currency`	A moeda de exibição do cliente. Não converte os valores das respostas.

Usar o token

Mande o token em toda leitura, no cabeçalho:

Authorization: Bearer <access_token>

O token vale dois minutos. A vida curta é intencional: permite revogar um acesso sem manter uma lista de revogações e faz cada leitura ser verificada por assinatura, sem consultar banco de dados.

Renovação

Guarde expires_at junto com o token.
Renove antes de expirar, com uma folga de uns 15 segundos. Não tente adivinhar o relógio do servidor: use a resposta.
Se uma leitura devolver 401 com INVALID_TOKEN, troque a chave por um novo token e repita a leitura uma vez.
Não guarde o token em disco nem em cache compartilhado. Ele é barato de obter.
Uma tarefa que lê muitas rotas em sequência pode reaproveitar o mesmo token por até dois minutos. Para tarefas longas, renove por tempo, não por contagem de chamadas.

Cabeçalhos

Cabeçalho	Quando	Valor
`Authorization`	Sempre	`Bearer <chave>` em `/v1/token`; `Bearer <token>` nas leituras.
`Accept`	Opcional	`application/json`.

Não existe cabeçalho nem cookie que troque de cliente. O cliente vem sempre do caminho e é conferido com o do token.

Erros de autenticação e autorização

Status	`error.code`	Quando	O que fazer
401	`SEM_CHAVE`	`POST /v1/token` sem o cabeçalho `Authorization`.	Envie `Authorization: Bearer <chave>`.
401	`CHAVE_INVALIDA`	A chave não tem o formato esperado, não existe, venceu ou foi revogada. A resposta não diz qual dos casos, de propósito.	Confira o valor; se persistir, peça outra chave.
401	`NO_TOKEN`	Leitura sem `Authorization: Bearer`.	Envie o token.
401	`INVALID_TOKEN`	Token malformado, vencido ou com assinatura inválida.	Troque a chave por um novo token.
403	`TENANT_MISMATCH`	O token é válido, mas o cliente do caminho não é o do token.	Use o `tenant_id` devolvido pela troca.
403	`FORBIDDEN`	O papel da chave não inclui a permissão da rota.	Veja Permissões e escopo.

O 403 nunca é disfarçado de 404 nem de resposta vazia. Uma resposta vazia seria indistinguível de “não há dados”, e você chegaria à conclusão errada.

Um caso à parte: as rotas de detalhe de público (/publicos/{id}) respondem 404 quando o identificador existe mas pertence a outro cliente. Nesse caso o 404 não prova que o recurso não existe.