Pular para o conteúdo principal

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.

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.
  • 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:

EscopoUsoExemplos de endpoint
api-sigades-consultarConsultas (leitura) em qualquer recurso.GET /v2/agente/..., GET /v2/eventos/{idEvento}
api-sigades-documentoUpload, fase de assinatura e captura de documentos.POST /v2/documentos/...
api-sigades-encaminhamentoCriação, resposta, reencaminhamento e complementação de encaminhamentos.POST /v2/encaminhamento/...
api-sigades-processoAtos processuais (autuar, despachar, avocar, entranhar, etc.).POST /v2/processos/...
api-organogramaConsulta 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​

  • O token tem validade limitada (campo expires_in, em segundos). Renove antes da expiração.
  • Em fluxo authorization_code, utilize o refresh_token (quando solicitado o escopo offline_access).
  • Em client_credentials, basta solicitar um novo token.

Erros comuns​

  • 401 Unauthorized: token ausente, expirado ou inválido. Renove o 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.

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.