Autenticação

Para garantir a segurança, integridade e validade jurídica das operações, o E-Docs exige autenticação baseada em OAuth 2.0, provida pelo Acesso Cidadão.

Pré-requisito

Antes de autenticar, o sistema precisa estar cadastrado no Acesso Cidadão e ter permissões aprovadas. Veja Solicitação de Acesso.

Qual fluxo usar

Necessidade do sistema	Fluxo
Consultar dados públicos e metadados de processos, documentos e encaminhamentos, sem usuário	client_credentials
Ler o conteúdo de documentos	authorization_code ou hybrid
Capturar, assinar, encaminhar ou praticar atos processuais	authorization_code ou hybrid

O sistema precisa levar o usuário à tela de login do Acesso Cidadão

Nos fluxos com usuário (authorization_code ou hybrid), o sistema não consegue obter o token sozinho: quando o usuário ainda não está logado, ou quando o token expirou, o sistema deve redirecionar o navegador do usuário para a tela de login do Acesso Cidadão (o endpoint de autorização), para que a própria pessoa se autentique. Só depois do login o Acesso Cidadão devolve um código, que o sistema troca pelo token. Isso vale para qualquer sistema, inclusive os que automatizam ou assistem tarefas (robôs, serviços de análise, IA): se a ação depende de um usuário, o sistema precisa de uma interface em que a pessoa possa fazer esse login, e nenhuma credencial do sistema substitui isso.

O que cada fluxo enxerga

O fluxo client_credentials, sem usuário associado, permite consultar metadados de processos, documentos e encaminhamentos, mas não dá acesso ao conteúdo dos documentos.

O acesso ao conteúdo é exclusivo de usuário autenticado. A visibilidade é sempre a do usuário logado: o sistema só vê, pela integração, o que esse usuário já poderia ver diretamente no E-Docs, limitada às suas permissões e aos níveis de restrição de acesso (Público, Organizacional, Sigiloso e Classificado). Veja Restrição de Acesso.

Não existe credencial que permita a um sistema enxergar o acervo de um órgão de forma ampla e independente de usuário. A API opera sobre processos e documentos identificados individualmente, a partir da atuação de um usuário autenticado.

Isso vale também para robôs e sistemas de inteligência artificial que leem o conteúdo de documentos. O desenho viável é aquele em que um servidor, no curso do seu trabalho sobre um processo específico, aciona o processamento daquele processo. O órgão responsável pelo sistema decide quem pode usá-lo, com que alcance e que uso será feito do conteúdo extraído.

Fluxos de Autenticação

1. Authorization Code / Hybrid (com usuário)

Obrigatório para qualquer ação que envolva autoria (captura de documentos, assinatura, atos processuais, encaminhamentos). O token carrega a identidade do usuário logado.

• Fluxos OAuth 2.0: authorization_code (recomendado) ou hybrid.
• Captura, assinatura, encaminhamentos e atos processuais exigem o padrão Hybrid e o provedor de login atual do Acesso Cidadão. Uma migração para o novo login do Acesso Cidadão é esperada no futuro; os responsáveis por sistemas integrados serão informados previamente.
• Endpoint de autorização (Acesso Cidadão): https://acessocidadao.es.gov.br/is/connect/authorize
• Endpoint de token: https://acessocidadao.es.gov.br/is/connect/token

2. Client Credentials (sem usuário)

Utilizado para automações, monitoramento ou consultas que não dependem de um usuário específico. Restrito a leitura de dados públicos/metadados.

• Fluxo OAuth 2.0: client_credentials.
• Endpoint de token: https://acessocidadao.es.gov.br/is/connect/token

Escopos da API E-Docs

Solicite no token apenas os escopos necessários para a operação que será executada:

Escopo	Uso	Exemplos de endpoint
api-sigades-consultar	Consultas (leitura) em qualquer recurso.	GET /v2/agente/..., GET /v2/eventos/{idEvento}
api-sigades-documento	Upload, fase de assinatura e captura de documentos.	POST /v2/documentos/...
api-sigades-encaminhamento	Criação, resposta, reencaminhamento e complementação de encaminhamentos.	POST /v2/encaminhamento/...
api-sigades-processo	Atos processuais (autuar, despachar, avocar, entranhar, etc.).	POST /v2/processos/...
api-organograma	Consulta direta à API do Organograma (caso seu sistema integre também ao Organograma).	GET https://api.organograma.es.gov.br/...

Combine escopos

Solicite múltiplos escopos no mesmo token quando uma operação cruzar áreas. Ex.: para capturar e em seguida encaminhar, solicite api-sigades-documento api-sigades-encaminhamento api-sigades-consultar.

Como obter o Bearer Token

Exemplo: Client Credentials (curl)

curl -X POST https://acessocidadao.es.gov.br/is/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "scope=api-sigades-consultar"

Resposta (exemplo):

{
  "access_token": "eyJhbGciOiJSUzI1...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api-sigades-consultar"
}

Exemplo: Authorization Code (resumo do fluxo)

1. Redirecione o usuário para:

   https://acessocidadao.es.gov.br/is/connect/authorize
     ?client_id=SEU_CLIENT_ID
     &response_type=code
     &scope=openid api-sigades-documento api-sigades-consultar
     &redirect_uri=https://seu-sistema/callback
     &state=XYZ
2. Após o login, o Acesso Cidadão redireciona para redirect_uri com code=....
3. Troque o code por um token:

   curl -X POST https://acessocidadao.es.gov.br/is/connect/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "client_id=SEU_CLIENT_ID" \
     -d "client_secret=SEU_CLIENT_SECRET" \
     -d "code=CODIGO_RECEBIDO" \
     -d "redirect_uri=https://seu-sistema/callback"

Uso do Token nas chamadas

Envie o token no cabeçalho Authorization como Bearer Token (RFC 6750):

curl https://api.treinamento.e-docs.es.gov.br/v2/agente/patriarcas \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1..."

Renovação e Validade

• Token de usuário (authorization_code ou hybrid): validade de 1 hora, por requisito da solução de assinatura eletrônica. A renovação ocorre apenas por nova autenticação do usuário. O escopo offline_access (renovação sem o usuário) não é concedido nas integrações com a API do E-Docs. A expiração é comportamento esperado.
• Token sem usuário (client_credentials): basta solicitar um novo token. Renove antes da expiração (campo expires_in).

Erros comuns

• 401 Unauthorized: token ausente, expirado ou inválido. Com token de usuário, a aplicação deve tratar o 401 redirecionando o usuário ao endpoint de autorização do Acesso Cidadão. Com client_credentials, solicite um novo token.
• 403 Forbidden: token válido, mas sem o escopo necessário ou sem permissão para o recurso. Verifique escopos e a Solicitação de Acesso.

Autoria e titularidade do token

• Todo ato com autoria (captura, assinatura, encaminhamento, ato processual) é atribuído ao titular do token usado na chamada, e o papel informado deve pertencer a esse titular. Os papéis do titular são consultados em GET /v2/usuario/papeis.
• Não existe ato em nome de terceiro, e o sistema não captura documentos em nome próprio. O ato fica registrado em nome do usuário, com o sistema indicado como agente do tipo Sistema.
• Uma automação (robô, serviço de análise, IA) que precise capturar ou anexar documentos deve ser acionada por um usuário autenticado; o ato é registrado em nome dele.

Observações Técnicas

• Validade Jurídica: o E-Docs utiliza o login do Acesso Cidadão como meio seguro de identificação do usuário, indispensável à integridade dos documentos e atos.
• Boas práticas: armazene client_secret com segurança (variáveis de ambiente / cofre); nunca exponha em código-fonte público.
• Cache do token: reutilize o mesmo token enquanto válido; evite solicitar um novo a cada requisição.