Apps de terceiros (OAuth 2.0)

A chave de API da conta resolve a integração da sua própria conta com os seus sistemas. Quando o objetivo é publicar um app que outras contas instalam, a credencial certa é um token OAuth 2.0 emitido no consentimento do dono da conta, com escopos aceitos por ele e renovação sem nova autorização.

Situação atual

O fluxo OAuth 2.0 para apps de terceiros ainda não está disponível na API pública. Esta página existe para você planejar com antecedência e para não construir sobre a credencial errada.

Enquanto isso, o caminho suportado para integrar uma conta é a chave de API da conta, criada pelo próprio dono da conta e entregue ao integrador por um canal seguro.

O que já está decidido

• O token de app nasce de um consentimento explícito do dono da conta, com a lista de escopos na tela.
• Os escopos do app são os mesmos do catálogo. Não haverá um conjunto paralelo.
• Revogar o app pela conta invalida todos os tokens dele para aquela conta, na hora.
• O app nunca recebe a sessão da pessoa nem credenciais administrativas.

Glossário do desenvolvedor

• Conta: o espaço do cliente no Nexus. Chaves e tokens pertencem a uma conta.
• Subconta: o espaço do CRM associado a uma operação dentro da conta. Algumas credenciais são limitadas a uma subconta.
• Escopo: permissão nomeada, como instances:read. A credencial carrega um conjunto de escopos e a operação exige um deles.
• Token de acesso: credencial de curta duração que um app usa para chamar a API em nome de uma conta.
• Token de renovação: credencial que troca um token de acesso vencido por um novo, sem nova autorização da pessoa.
• Consentimento: a tela em que o dono da conta vê o que o app pede e aceita ou recusa.
• Revogação: o ato de encerrar uma credencial. No Nexus é imediato, sem carência.
• Chave de idempotência: identificador único de uma intenção, usado para repetir uma operação sem duplicar o efeito.
• Identificador de correlação: valor devolvido em erros e logs para localizar a requisição no suporte.

Como se preparar hoje

1. Construa a integração contra a chave de API da conta, isolando a credencial num único ponto do código.
2. Peça só os escopos de que precisa. A migração para OAuth vai pedir os mesmos.
3. Trate 401 como "credencial precisa ser renovada ou trocada", não como erro fatal. Com OAuth, isso vira a renovação do token.
4. Acompanhe o changelog: a abertura do OAuth será anunciada ali, com prazo e guia de migração.