Instalação e consentimento

Nenhum aplicativo acessa dados de um projeto sem o consentimento de um administrador desse projeto. Esta página mostra o fluxo dos dois lados.

Quem pode instalar

Instalar e desinstalar exige a permissão de instalar aplicativos no projeto, que a owiew concede por padrão ao dono e ao administrador. A instalação e a desinstalação também pedem uma confirmação recente de segundo fator (código do autenticador ou passkey).

O que o administrador vê

1. Em Aplicativos, a loja lista os aplicativos disponíveis para o projeto. Em Ver detalhes, ele vê a descrição, a versão, os escopos com risco e o aviso de dados pessoais, quando houver. Aplicativos receptores mostram os domínios que recebem os dados.
2. Ele clica em Instalar. A owiew não grava a instalação neste ponto.
3. A owiew abre a tela de autorização. A tela mostra quem pede a instalação, os projetos que ele pode escolher (só aparecem os projetos em que ele pode instalar aplicativos), os escopos com o texto exato, o risco de cada um, a restrição de IP quando existir e os endereços de webhook.
4. Se algum escopo expõe dados pessoais, ele precisa marcar o aceite expresso (“Entendo e autorizo o acesso a dados pessoais”).
5. Ele confirma o segundo fator e clica em Autorizar. Negar encerra o fluxo sem instalar.

O que o seu aplicativo faz (modo oauth)

O fluxo é OAuth 2.1 com PKCE.

1. A owiew envia o administrador ao endereço de instalação do seu aplicativo, com os parâmetros iss (o emissor) e client_id.
2. Seu aplicativo gera um code_verifier aleatório, calcula o code_challenge com SHA-256 e redireciona o navegador do administrador para a tela de autorização da owiew, em https://auth.owiew.com/oauth2/app-consentimento, com estes parâmetros:

Parâmetro	Obrigatório	Regra
client_id	sim	O identificador do seu aplicativo
redirect_uri	sim	Igual a um dos endereços de retorno cadastrados (comparação exata)
code_challenge	sim	Base64url sem preenchimento, de 43 a 128 caracteres
code_challenge_method	sim	S256. O método plain é recusado
state	recomendado	Até 512 caracteres. Use para ligar o retorno ao pedido
projetos	não	Sugestão de projetos, separados por vírgula (até 50)

3. Depois do consentimento, a owiew devolve o navegador ao redirect_uri com um código de autorização. O código vale 1 minuto e só pode ser usado uma vez.
4. Seu backend troca o código no endpoint de token, com grant_type=authorization_code, code, redirect_uri e code_verifier, autenticado por client_secret_basic.
5. A resposta traz o token de app, o installation_id e a lista de projetos consentidos. Não há refresh_token nem id_token. Guarde o installation_id: é com ele que você pede novos tokens.

A troca do código atende o primeiro projeto consentido. Para os demais, peça tokens por client_credentials informando o project_id, como descrito em modelo de acesso.

O que o aplicativo recebe (modo receptor)

Um aplicativo receptor não faz OAuth. O administrador é levado direto à tela de autorização da owiew, escolhe os projetos e autoriza. Depois disso, a owiew passa a entregar os eventos assinados no endereço cadastrado. O aplicativo não tem credencial, não obtém token e não chama a API.

Trava de IP opcional

O aplicativo ou a instalação pode ter uma lista de endereços de origem permitidos, desligada por padrão. Quando ligada, ela vale para três pontos: a troca de token, as chamadas à API e a conexão de saída do webhook. Fora da lista, a troca responde 403 access_denied e a API responde 403 acesso-negado.

Desinstalar

O administrador clica em Desinstalar no aplicativo, confirma o segundo fator e a owiew revoga a instalação daquele projeto. Os outros projetos da mesma instalação seguem como estão.

O que acontece com o seu aplicativo:

• Token já emitido: deixa de funcionar em poucos minutos. As chamadas passam a receber 401 nao-autenticado, sem informar o motivo. O limite é de 2 minutos, que é a validade do token.
• Novo token para o projeto: o pedido é recusado com invalid_grant.
• Webhook: as entregas pendentes daquele projeto são descartadas e nenhuma nova é criada. Seu receptor nunca recebe evento de um projeto sem consentimento.
• Dados do projeto: nada é apagado no projeto. O que o seu sistema já recebeu continua sob a responsabilidade do seu sistema.
• Reinstalar: o administrador pode instalar de novo, com um novo consentimento.

A desinstalação também pode ocorrer por revogação da própria owiew ou do desenvolvedor, e quando um aplicativo é suspenso. O efeito sobre o token é o mesmo.

Próximos passos

• Modelo de acesso
• Eventos e webhooks
• Limites e erros