Permissões (scopes)
Referência completa dos scopes do OrbitSender — o que cada um libera, se um parceiro pode obtê-lo e como pedir permissões no portal.
Cada scope é uma permissão granular. Seu app só recebe um token com os scopes que foram aprovados por um superadmin do OrbitSender e consentidos pelo usuário na tela de autorização. O escopo efetivo de um token é sempre um subconjunto dos scopes aprovados do app.
Elegibilidade do parceiro: allow, high e block
Para apps de parceiro, cada scope se enquadra em um destes níveis:
- allow — aprovável no fluxo normal de revisão.
- high — sensível. Exige vetting reforçado do app e consent explícito do usuário (o scope aparece destacado na tela de consentimento).
- block — nunca é concedido a parceiro. Vale para todos os scopes
integrations:*(ingerem/expõem segredos brutos de marketplace) ewebhooks:*(operam o webhook da conta do dono).
Elegibilidade de parceiro ≠ uso por API key
Quase todos os scopes também podem ser usados por uma API key do próprio tenant. A elegibilidade de parceiro (allow/high/block) descreve apenas o que um app de parceiro pode obter via OAuth. fastlogin:create é a única exceção: é exclusivo de parceiro e não existe para API key.
Catálogo completo de scopes
| Scope | O que libera | Elegibilidade (parceiro) | Tipo |
|---|---|---|---|
general:read | Validar a chave/token (ping). | allow | leitura |
channels:read | Listar/ler canais (mascarado para parceiro). | allow | leitura |
channels:write | Criar/editar/desconectar/excluir canais. | high | escrita |
segments:read | Listar segmentos e grupos (JIDs mascarados p/ parceiro). | high | leitura |
segments:write | Criar/editar segmentos. | allow | escrita |
monitoring:write | Configurar monitoramento de grupo (automação/afiliado). | high | escrita |
campaigns:read | Ler/listar campanhas (status/progresso agregado). | allow | leitura |
campaigns:send | Disparar campanha (QuickSender/imediato). | high | escrita |
settings:read | Ler configurações (branding p/ parceiro; sem cadência anti-ban). | high | leitura |
settings:write | Alterar configurações de disparo. | high | escrita |
integrations:read | Listar integrações de marketplace. | Bloqueado | leitura |
integrations:write | Criar/editar integrações (ingere segredos brutos). | Bloqueado | escrita |
webhooks:read | Ler URLs de webhook da conta (só dono/api-key). | Bloqueado | leitura |
webhooks:write | Editar/testar webhooks da conta (só dono/api-key). | Bloqueado | escrita |
statistics:read | Ler estatísticas agregadas do tenant (sem PII). | allow | leitura |
fastlogin:create | Gerar link de fastlogin (sessão do usuário). Só parceiro. | high | escrita |
integrations:* nunca é liberado
integrations:read e integrations:write são sempre bloqueados para parceiros, sem exceção. Eles dariam acesso a credenciais de marketplace em texto puro. Não peça esses scopes — o pedido será recusado na revisão.
webhooks:* é do dono da conta — você usa o webhook do app
webhooks:read e webhooks:write operam o webhook da conta (do próprio dono/api-key) e são bloqueados para parceiros. Para receber eventos, você não pede scope de webhook: configura o webhook do seu app no Portal do Desenvolvedor, que recebe de todas as contas credenciadas com tenant_ref opaco. Veja Receber webhooks.
Como pedir scopes
Você declara os scopes desejados ao criar/editar o app no Portal do Dev, com uma justificativa por scope. A revisão é feita por-scope por um superadmin.
Peça apenas o mínimo
Solicite só o que seu caso de uso exige. Scopes high demandam justificativa mais forte e passam por vetting reforçado.
Escreva uma justificativa clara
Explique, para cada scope, o que seu app faz com aquela permissão. Isso acelera a aprovação.
Aguarde a aprovação
O app precisa estar com status approved antes de o /authorize funcionar. Enquanto um scope não estiver aprovado, ele não pode ser consentido nem entrar no token.
Alterar scope reabre a revisão
Adicionar ou alterar um scope reabre a revisão daquele scope. O app pode continuar operando com os scopes já aprovados, mas o novo scope só passa a valer após aprovação.
Veja o passo a passo em Criar e configurar o app.
Máscara e scopes exclusivos
Mesmo com um scope de leitura aprovado, um parceiro nunca recebe PII. Quando a chamada vem de um app de parceiro (via='partner_app'), a resposta passa por uma allowlist default-deny: telefones, JIDs de grupo, nomes de contato e a cadência anti-ban são removidos, e ids internos de canal viram referências opacas (channel_ref). Detalhes em Chamar a API + máscara.
O scope fastlogin:create é exclusivo de parceiro e gera um link SSO de sessão de-escalada. Entenda os limites dessa sessão em Fastlogin.