API: autenticação

A API usa OAuth 2.0 no fluxo client credentials. O token é emitido pelo Acesso Cidadão para o sistema consumidor, e não para uma pessoa.

Pré-requisitos

1. O sistema consumidor precisa de um cliente (client) cadastrado no Acesso Cidadão, com client_id e client_secret.
2. O cliente precisa ter acesso ao escopo api-organograma-base.
3. O cliente é liberado para um ambiente. Um token de homologação não funciona em produção, e vice-versa.

O cadastro do cliente e a liberação do escopo são solicitados pelos canais de atendimento do Acesso Cidadão para desenvolvedores. Informe o sistema consumidor, a finalidade do uso e o ambiente desejado.

Guarde o segredo

O client_secret é uma credencial do sistema. Guarde-o em um cofre de segredos ou em variáveis de ambiente protegidas, nunca no código-fonte nem em aplicações que rodam no navegador ou no celular.

Obter o token

Item	Valor
Emissor	https://token.acessocidadao.es.gov.br/
Documento de descoberta	https://token.acessocidadao.es.gov.br/.well-known/openid-configuration
Endpoint de token	o token_endpoint informado no documento de descoberta
grant_type	client_credentials
scope	api-organograma-base

Recomenda-se ler o endereço do token no documento de descoberta, como fazem as bibliotecas de OAuth. Os exemplos abaixo usam o endereço padrão https://token.acessocidadao.es.gov.br/connect/token.

curl

curl -s -X POST "https://token.acessocidadao.es.gov.br/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=api-organograma-base"

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api-organograma-base"
}

Chamar a API

curl -s "https://apiv2.organograma.es.gov.br/v2/patriarcas/$ID_PATRIARCA/orgaos" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PowerShell

$token = Invoke-RestMethod -Method Post `
  -Uri "https://token.acessocidadao.es.gov.br/connect/token" `
  -Body @{
    grant_type    = "client_credentials"
    client_id     = $env:CLIENT_ID
    client_secret = $env:CLIENT_SECRET
    scope         = "api-organograma-base"
  }

Invoke-RestMethod `
  -Uri "https://apiv2.organograma.es.gov.br/v2/patriarcas/$env:ID_PATRIARCA/orgaos" `
  -Headers @{ Authorization = "Bearer $($token.access_token)" }

C# (.NET)

Exemplo com o pacote Duende.IdentityModel, que lê o documento de descoberta:

using Duende.IdentityModel.Client;
using System.Net.Http.Json;

var http = new HttpClient();

var disco = await http.GetDiscoveryDocumentAsync("https://token.acessocidadao.es.gov.br/");
if (disco.IsError) throw new Exception(disco.Error);

var token = await http.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
    Address = disco.TokenEndpoint,
    ClientId = Environment.GetEnvironmentVariable("CLIENT_ID"),
    ClientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET"),
    Scope = "api-organograma-base",
});
if (token.IsError) throw new Exception(token.Error);

http.SetBearerToken(token.AccessToken!);

var idPatriarca = Environment.GetEnvironmentVariable("ID_PATRIARCA");
var orgaos = await http.GetFromJsonAsync<List<Orgao>>(
    $"https://apiv2.organograma.es.gov.br/v2/patriarcas/{idPatriarca}/orgaos");

public record Orgao(Guid Id, string Nome, string Sigla, Guid IdPatriarca);

Validade e renovação

O token vale pelo tempo indicado em expires_in (em segundos). Reutilize o mesmo token em todas as chamadas e peça um novo pouco antes de ele expirar. Pedir um token por chamada é desnecessário e deixa a integração mais lenta.

Problemas comuns

Sintoma	Causa provável
invalid_client ao pedir o token	client_id ou client_secret incorretos
invalid_scope ao pedir o token	O cliente não tem acesso ao escopo api-organograma-base
401 na API	Token ausente, expirado ou enviado sem o prefixo Bearer
403 na API	Token sem o escopo api-organograma-base ou emitido para outro ambiente