"None of the requested scopes are authorized": o 400 que parece credencial errada
Existe uma falha de integração que consome uma tarde e termina numa linha de configuração: o token não sai, o erro fala de autorização, e a suspeita recai sobre o client_id e o client_secret — que estão corretos. A mensagem é None of the requested scopes are authorized, e ela é literalmente verdadeira e completamente enganosa ao mesmo tempo. Nenhum dos escopos pedidos está autorizado porque nenhum deles existe. Este guia mostra por que isso acontece, quais são os escopos reais, e o caso pior — aquele em que o escopo errado não gera erro nenhum e a falha aparece depois, longe da causa.
Antes de desconfiar da credencial: confira a string de escopos. Este 400 chega no passo da autenticação e fala em autorização, mas o client_id e o client_secret costumam estar perfeitos. O problema é um escopo que não existe.
O erro
O endpoint filtra os escopos pedidos contra os concedidos à credencial. Quando a interseção é vazia, ele recusa. No exemplo acima a interseção é vazia por um motivo simples: envelopes:write não existe — nunca existiu.
Os seis escopos reais
| Escopo | Permite |
|---|---|
transactions:write |
Criar e alterar fluxos: transações, sessões, envelopes, upload, cadastro biométrico, cancelamentos |
transactions:read |
Consultar transações, sessões, envelopes, status e download |
steps:write |
Listar, iniciar e concluir etapas de verificação |
evidence:read |
Obter o pacote de evidências |
webhooks:write |
Cadastrar, listar, remover e testar webhooks |
verification:write |
Verificação autenticada de documento |
É a lista inteira. Não existem envelopes:read, envelopes:write, signing-sessions:read, signing-sessions:write, documents:write, templates:*, audit:read nem org:admin. Todos parecem plausíveis, e é exatamente por isso que aparecem.
Por que o nome não segue a rota
A dedução natural — rota /v1/envelopes, logo escopo envelopes:* — falha porque os escopos foram desenhados em torno de capacidades, não de caminhos de URL.
Criar um envelope, criar uma sessão de assinatura, subir um documento e cadastrar uma biometria são todos exercícios da mesma capacidade: iniciar ou alterar um fluxo de assinatura. Por isso todos autorizam em transactions:write.
Isso tem uma vantagem concreta: quando a API ganha uma rota nova dentro de uma capacidade existente, as credenciais já emitidas continuam funcionando. Um escopo por recurso obrigaria a reemitir credenciais a cada endpoint novo. O custo é a surpresa que este artigo resolve — o mapa completo, rota por rota, está em por que o seu token falha.
O caso pior: o escopo errado que não dá erro
O filtro só recusa quando nada sobra. Isto passa sem reclamar:
Um escopo digitado errado no meio de uma lista boa não gera erro nenhum na emissão. A falha aparece depois, como 403 na rota que dependia do escopo descartado — longe, no tempo e no código, da linha que a causou.
Daí a rotina de diagnóstico correta: quando uma rota devolve 403 com uma credencial que funciona em todo o resto, não olhe para a rota primeiro. Decodifique o token emitido e compare a lista de escopos que ele carrega com a que você pediu. A diferença é o defeito.
Duas armadilhas de leitura
Listar webhooks exige webhooks:write. Não existe webhooks:read — as quatro rotas de webhook ficam sob o mesmo escopo de escrita.
Listar etapas exige steps:write. É uma leitura sob escopo de escrita, porque as três rotas de etapa foram agrupadas por atividade: quem lista etapas está conduzindo o fluxo do signatário, não observando de fora. Se a sua integração só acompanha o andamento, use a consulta da transação com transactions:read — mais barato em permissão e suficiente.
Se você copiou de um exemplo antigo
Vale procurar no seu código e na sua configuração por estas strings, porque nenhuma delas existe:
As duas primeiras chegaram a ser publicadas em guias nossos, em vários lugares, inclusive em trechos prontos para copiar; a última apareceu num README de SDK. Tudo corrigido — mas material antigo continua circulando, e um trecho copiado há seis meses não se atualiza sozinho.
Conjuntos que funcionam
Note que webhooks:write aparece sozinho: ele pertence à rotina de configuração, não ao serviço que roda em produção. Separar as duas credenciais custa pouco e evita que um token de aplicação possa reapontar os seus webhooks.
Roteiro de diagnóstico
- 400 na emissão? Compare a sua string com a lista de seis. Um nome fora dela é a causa mais provável.
- 403 numa rota específica? Decodifique o token e veja quais escopos ele realmente carrega.
- 401, e não 403? Aí é outro problema: credencial, token vencido (a validade é de 900 segundos) ou uma rota que não aceita Bearer — ver o erro 401 e o token de embed.
- Sem certeza do que a API respondeu? O painel mostra, ao lado de cada requisição que falhou, uma explicação e uma linha de como corrigir — ver o painel de API.
Para o mecanismo de autenticação em si, veja OAuth2 e autenticação segura e como obter as credenciais. Para o conjunto de recursos que esses escopos autorizam, a visão geral da API de assinatura eletrônica.
Perguntas Frequentes
O que significa esse erro?
Que a interseção entre os escopos que você pediu e os que a sua credencial tem é vazia. O endpoint de token filtra o pedido contra a lista concedida e, quando não sobra nada, responde 400. Como isso acontece no passo da autenticação e a mensagem fala em autorização, quase todo mundo começa investigando a credencial.
Quais são os escopos válidos?
Seis, e apenas seis: transactions:write, transactions:read, steps:write, evidence:read, webhooks:write e verification:write. Qualquer outro nome é inventado.
Por que meu escopo "envelopes:write" não funciona?
Porque ele não existe. Os escopos descrevem capacidades, não caminhos de URL — as rotas de envelopes, sessões de assinatura, sessões de confiança e cadastro de usuários autorizam todas em transactions:read ou transactions:write. Deduzir o escopo a partir do nome da rota é a origem mais comum desse 400.
Pedi um escopo válido e um inválido. Por que não deu erro?
Porque o filtro é por interseção e só recusa quando o resultado é vazio. Se ao menos um escopo for válido e concedido, o token sai — com os válidos, e o inválido descartado em silêncio. É conveniente e traiçoeiro: a falha reaparece depois como 403 na rota que dependia do escopo perdido.
Como sei quais escopos o meu token realmente carrega?
Decodificando o token emitido e comparando com o que você pediu. A diferença entre as duas listas é exatamente o defeito. É o primeiro passo de diagnóstico quando uma rota devolve 403 com uma credencial que funciona em todo o resto.
Copiei de um exemplo antigo e não funciona. Por quê?
É provável que o exemplo trouxesse escopos que nunca existiram. Guias nossos chegaram a publicar signing-sessions:read e signing-sessions:write em vários lugares, incluindo trechos de copiar e colar, e um README de SDK trazia um documents:write inexistente. Foi corrigido — mas material antigo circula.
Qual conjunto mínimo devo pedir?
Para criar e acompanhar: transactions:write transactions:read. Acrescente evidence:read se for baixar o pacote de evidências, steps:write só se conduzir as etapas por conta própria, e deixe webhooks:write para a credencial de configuração, separada da que roda em produção.
Comece com a string de escopos certa
Seis escopos, e nenhum leva o nome de um recurso. As credenciais de homologação são gratuitas e permitem testar a emissão do token em minutos.
Criar credenciais de homologação Fale com o time comercial