Modelo de acesso

Quem chama a /apps/v1 é o backend do seu aplicativo, com um token de app. O token identifica o aplicativo, a instalação e um projeto. Ele nunca identifica uma pessoa.

Características

Propriedade	Valor
Formato	JWT assinado (JWS compacto) com EdDSA (Ed25519)
Cabeçalho	`{"alg":"EdDSA","typ":"APT","kid":"v1"}`
Emissor (`iss`)	`owiew-iam`
Audiência (`aud`)	`owiew-apps` (texto, não lista)
Validade	2 minutos (`exp = iat + 120`)
Renovação	Peça outro token. Não há refresh token nem sessão
Tolerância de relógio	30 segundos
Escopo de projeto	Exatamente um projeto por token

O tipo do token (APT) fica no cabeçalho assinado, não nas claims.

Claims

{
  "iss": "owiew-iam",
  "aud": "owiew-apps",
  "sub": "app:app_01JC8M4Z2QXW5N7R9T3V6B0KHE",
  "tid": "<identificador do projeto>",
  "iid": "ins_01JC8M9A7D3F5H2K4N6P8R0STV",
  "scp": ["instalacao:read"],
  "jti": "9f1c3e5a7b2d4f6081a3c5e7092b4d6f",
  "iat": 1792000000,
  "exp": 1792000120
}

Os valores acima são de exemplo.

Claim	Significado
`sub`	`app:` mais o identificador do aplicativo
`tid`	O projeto a que este token dá acesso
`iid`	O identificador da instalação (`ins_` mais 26 caracteres)
`scp`	Lista dos escopos efetivos. Sempre contém `instalacao:read`
`jti`	Identificador único do token (32 caracteres hexadecimais)

O token não carrega permissão de pessoa, papel, e-mail nem sessão. Um token com qualquer claim desse tipo é recusado.

Como obter um token

Faça um POST ao endpoint de token do IAM da owiew. A descoberta fica em https://auth.owiew.com/.well-known/openid-configuration e informa o endereço do endpoint e a chave pública.

Use o fluxo client_credentials e autentique o cliente com client_secret_basic: o cabeçalho Authorization: Basic leva client_id:segredo, com cada parte codificada como URL e o conjunto em base64. O segredo nunca vai no corpo nem na URL.

Parâmetros do formulário (application/x-www-form-urlencoded):

Campo	Obrigatório	Descrição
`grant_type`	sim	`client_credentials`
`installation_id`	sim	A instalação (`ins_...`)
`project_id`	quando a instalação tem mais de um projeto ativo	Escolhe qual projeto consentido o token vai cobrir
`scope`	não	Subconjunto dos escopos da instalação, separados por espaço. Sem ele, vêm todos

Requisição de exemplo:

curl -sS -X POST "https://auth.owiew.com/oauth2/token" \
  -u "$OWIEW_CLIENT_ID:$OWIEW_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d installation_id="$OWIEW_INSTALLATION_ID" \
  -d project_id="$OWIEW_PROJECT_ID"

Resposta de exemplo (os cabeçalhos trazem Cache-Control: no-store):

{
  "access_token": "<token de app>",
  "token_type": "Bearer",
  "expires_in": 120,
  "scope": "instalacao:read",
  "installation_id": "ins_01JC8M9A7D3F5H2K4N6P8R0STV",
  "project_id": "<identificador do projeto>"
}

Para descobrir os projetos de uma instalação, chame GET /oauth2/app/instalacoes/{installation_id}/projetos com a mesma autenticação Basic. A resposta lista os projetos ativos para os quais você pode pedir token.

Erros do endpoint de token

Os erros seguem o formato OAuth (error e error_description).

Situação	Resposta
Cliente inexistente, segredo errado, vencido ou revogado	`401 invalid_client` (sempre igual, com `WWW-Authenticate: Basic`)
Instalação inexistente, de outro aplicativo, revogada, aplicativo suspenso, projeto não consentido	`400 invalid_grant`, com a mesma descrição fixa para todos os casos
Instalação com mais de um projeto e sem `project_id`	`400 invalid_request`
`scope` fora do que a instalação concede	`400 invalid_scope`
Origem fora da lista de IPs, quando a trava de IP está ligada	`403 access_denied`
Tentativas demais	`429 temporarily_unavailable` com `Retry-After`

A owiew devolve a mesma resposta para todas as falhas da instalação de propósito. Não tente deduzir o motivo pela mensagem.

Renovação

O token vale 2 minutos. Guarde-o em memória, calcule o vencimento com expires_in e peça um novo antes de expirar (uma margem de 10 segundos funciona bem). Para ler outro projeto da mesma instalação, peça outro token com o project_id correspondente.

Verificação offline

A owiew verifica o token em cada chamada, sem consultar o banco: confere a assinatura com a chave pública publicada em https://auth.owiew.com/.well-known/jwks.json (chave OKP, curva Ed25519, kid v1, resposta com cache público curto).

Seu aplicativo não precisa verificar o token que recebeu, porque quem o consome é a owiew. Se quiser inspecioná-lo, siga a ordem abaixo e recuse na primeira falha:

O token tem três partes em base64url e no máximo 4 KiB.
alg é exatamente EdDSA. Recuse none, HS256, RS256 e qualquer outro.
kid é um valor presente no JWKS.
typ é APT.
A assinatura confere com a chave do JWKS.
iss é owiew-iam e aud é a string owiew-apps.
exp não passou (com 30 segundos de tolerância) e exp - iat é no máximo 120.

Nunca confie em uma claim antes de a assinatura conferir.

O que o token não faz

Não vale na API de leitura por chave de API, nas rotas internas da owiew nem no portal.
Não escreve: as rotas de /apps/v1 são de leitura (GET).
Não sobrevive à desinstalação: a revogação alcança tokens ainda não vencidos em poucos minutos. Veja instalação e consentimento.