API de apps /apps/v1

A API de apps é a superfície que o backend do seu aplicativo chama, de servidor para servidor. Ela é separada da API de leitura por chave de API: tem token, rotas, limites e contrato próprios.

Base: https://api.owiew.com/apps/v1
Autenticação: Authorization: Bearer <token de app>, obtido como descrito em modelo de acesso.
Métodos: todas as rotas são GET. Outro método responde 405.
Formato: JSON. Erros usam application/problem+json (veja limites e erros).
Navegador: a API não habilita CORS. Chame sempre de um servidor, nunca do navegador.

O contrato completo está em apps-v1.openapi.yaml, em OpenAPI 3.1.

Como o acesso é decidido

O token é validado por inteiro (assinatura, alg, typ, iss, aud, prazo). Qualquer falha de credencial responde o mesmo 401, sem dizer o motivo.
A instalação não pode estar revogada, e o aplicativo não pode estar suspenso.
Com a trava de IP ligada, a origem precisa estar na lista. Fora dela, 403 acesso-negado.
O token precisa ter o escopo da rota. Sem ele, 403 escopo-insuficiente.

O projeto vem somente do token. Se você enviar tenant, project_id ou parecido em caminho, query, cabeçalho ou corpo, a owiew ignora, sem erro. Para ler outro projeto, use outro token.

Rota disponível

Ler a instalação

GET /apps/v1/instalacao

Devolve a identidade e os escopos da instalação que o token representa. Serve para descobrir em qual projeto o aplicativo está e para testar a credencial de ponta a ponta. Ela é respondida só a partir das claims do token, sem consulta a banco.

Escopo: instalacao:read (sempre presente).
Parâmetros: nenhum.

curl -sS "https://api.owiew.com/apps/v1/instalacao" \
  -H "Authorization: Bearer $OWIEW_APP_TOKEN"

Resposta 200 (valores de exemplo):

{
  "installation_id": "ins_01JC8M9A7D3F5H2K4N6P8R0STV",
  "app_id": "app_01JC8M4Z2QXW5N7R9T3V6B0KHE",
  "tenant_id": "<identificador do projeto>",
  "escopos": ["instalacao:read"],
  "token_expira_em": "2026-10-22T14:05:11Z"
}

Campo	Descrição
`installation_id`	A instalação do token
`app_id`	O aplicativo
`tenant_id`	O projeto a que este token dá acesso, um dos consentidos da instalação
`escopos`	Os escopos efetivos agora
`token_expira_em`	Quando o token expira (RFC 3339, UTC)

A resposta leva Cache-Control: no-store e os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.

Erros: 401 nao-autenticado, 403 acesso-negado ou escopo-insuficiente, 405, 429 limite-de-taxa, 503 indisponivel.

Rotas de dados (planejado)

As rotas de leitura de dados do projeto (métricas, conversões, relatórios) ainda não existem. Quando chegarem, elas seguirão o desenho abaixo, que já vale para o resto da API:

Paginação por cursor: parâmetros cursor (opaco, até 512 caracteres) e limite (de 1 a 200, padrão 50). A resposta traz itens e proximo_cursor (null na última página). Cursor adulterado ou de outra rota responde 400 pedido-invalido.
Recorte por token: sempre o projeto do token.
Dados pessoais: só aparecem quando o escopo declara dados pessoais. Caso contrário, o campo é omitido, não mascarado.
Três estados: lista vazia (200 com itens: []), erro (problem+json) e lista com dados.

Chamar /apps/v1 em uma rota que não existe responde 404.

Versionamento

A versão está no caminho (/apps/v1). Campos novos podem ser acrescentados a qualquer resposta: ignore campos desconhecidos. Para descontinuar uma versão, a owiew envia os cabeçalhos Deprecation e Sunset (RFC 8594) com no mínimo 180 dias de antecedência.