Autenticação e tokens

O CargaRH é protegida pelo Acesso Cidadão, usando o fluxo OAuth2 Client Credentials.
Toda requisição para a API deve incluir um token de acesso válido no cabeçalho HTTP.

Como obter o token

Importante

Como o Oauth2 é um padrão muito utilizado, principalmente o fluxo Client Credentials, normalmente existem bibliotecas oficiais em qualquer linguagem de programação para tratar da geração e renovação de tokens de forma automatizada. Em geral sempre recomendamos que sejam usadas essas bibliotecas oficiais já que a geração e renovação de tokens não é uma tarefa trivial.

O passo a passo completo para gerar o token (headers, body, exemplo em cURL, detalhes do JSON de resposta) está documentado na documentação para desenvolvedores do Acesso Cidadão:

👉 Como gerar um token de acesso para sistema
https://docs.developer.acessocidadao.es.gov.br/AutorizacaoSistemas/ComoGerarToken

Resumindo:

1. Seu sistema faz um POST para
   https://acessocidadao.es.gov.br/is/connect/token
2. Usa o client_id e client_secret fornecidos pelo PRODEST (via Basic Auth);
3. Envia no corpo pelo menos:
   • grant_type=client_credentials
   • scope={escopos-de-sistema-informados}
4. Recebe um JSON com:
   • access_token
   • token_type (sempre Bearer)
   • expires_in (segundos de validade, normalmente em torno de 1 hora)

Enviando o token para o CargaRH

Com o token em mãos, todas as chamadas para o CargaRH devem enviar o header:

Authorization: Bearer {access_token}

Exemplo de chamada (resumido):

POST /v3/Carga/organograma/{guidPatriarcaRaiz} HTTP/1.1
Host: api.cargarh.es.gov.br
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{ ... corpo da carga ... }

⚠️ Boas práticas

• Não gere um token novo a cada requisição.
• Reaproveite o mesmo token até ele expirar.
• Trate o token como um segredo (sem logar em texto plano, sem expor em front-end).

Importante

O token NÃO deve ser gerado para cada requisição. Os tokens costumam ter validade de uma hora e devem ser reaproveitados em todas as requisições durante essa janela de validade. Excesso de requisições de tokens dentro de uma janela muito pequenas de tempo podem fazer com o seu cliente seja bloqueado de forma automática.

Ambientes da API do CargaRH

O CargaRH está disponível nos seguintes endereços:

Homologação https://api.cargarh.hom.es.gov.br/

Produção https://api.cargarh.es.gov.br/

Sempre implemente e teste primeiro em homologação antes de solicitar o acesso em produção.

Exemplo em C#

Abaixo um exemplo de uso típico em aplicações .NET, utilizando o IdentityModel e o AccessTokenManagement para obter e renovar tokens automaticamente em segundo plano. Por favor, antes de um novo desenvolvimento sempre confira a documentação oficial do dotnet core já que esse é apenas um exemplo básico e pode mudar com novas versões.

using IdentityModel.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAccessTokenManagement(options =>
{
    options.Client.Clients.Add("cargarh", new ClientCredentialsTokenRequest
    {
        Address = "https://acessocidadao.es.gov.br/is/connect/token",
        ClientId = "SEU_CLIENT_ID",
        ClientSecret = "SEU_CLIENT_SECRET",
        Scope = "escopos-de-sistema-aqui"
    });
});

// HttpClient que já injeta o token automaticamente
builder.Services.AddClientAccessTokenHttpClient("cargarh", configureClient: client =>
{
    client.BaseAddress = new Uri("https://api.cargarh.es.gov.br/");
});

var app = builder.Build();
app.Run();

E um serviço de exemplo consumindo a API:

public class CargaRhService
{
    private readonly HttpClient _client;

    public CargaRhService(IHttpClientFactory factory)
    {
        _client = factory.CreateClient("cargarh");
    }

    public async Task<string> PingAsync()
    {
        var response = await _client.GetAsync("ping");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

💡 Esse padrão tira da aplicação a responsabilidade de “lembrar” de renovar o token: o AccessTokenManagement cuida disso, e o código só usa o HttpClient.