O Login Cidadão Gov.br expõe APIs REST protegidas por OAuth 2.0 / OpenID Connect (OIDC). Para consumi-las, a aplicação deve possuir um access_token válido e os escopos apropriados, além de enviá-lo no cabeçalho Authorization: Bearer {token}.

1. Recuperação de Identidade e Perfil (UserInfo)

Estes endpoints implementam a camada de identidade OIDC e retornam as declarações (claims) do usuário autenticado.

GET /api/userinfo

Alias de compatibilidade: GET /api/v5/person

• Propósito técnico: endpoint padrão para obter o conjunto de atributos de identidade do portador do token.

• Escopos necessários: openid é obrigatório. Para dados completos de perfil, inclua também o escopo profile.

• Funcionamento: o servidor valida o Authorization: Bearer {token}. Se válido, retorna um objeto JSON com o identificador único do sujeito (sub) e os claims conforme os escopos autorizados.

• Padrão de resposta: 200 OK com o esquema de dados da entidade Person. Token ausente, expirado ou inválido retorna 401 Unauthorized. Escopo insuficiente retorna 403 Forbidden.

GET /api/userinfo/picture

Alias de compatibilidade: GET /api/v5/person/picture

• Propósito técnico: fornece a imagem de perfil do usuário de forma otimizada para uso em aplicações web.

• Escopos necessários: openid e profile.

• Funcionamento: este endpoint processa a foto do perfil e a entrega codificada em Base64, pronta para uso em elementos HTML.

• Uso em aplicações: o retorno já pode ser utilizado diretamente como valor do atributo src de uma tag , pois é entregue no formato data:image/jpeg;base64,{conteúdo}.

• Padrão de resposta: 200 OK com a imagem. Caso não exista foto cadastrada, pode retornar corpo vazio (200 com conteúdo nulo) ou 404 Not Found. Requisições sem token válido retornam 401 Unauthorized.

2. Interoperabilidade com o Ecossistema Gov.br

Estes endpoints fazem a ponte entre o Login Cidadão e a plataforma Gov.br.

GET /api/govbr/companies

Alias de compatibilidade: GET /api/v5/person/login/govbr/dadosempresa

• Propósito técnico: consultar o vínculo de representação legal entre Pessoa Física (PF) e Pessoa Jurídica (PJ), com base nos dados da conta Gov.br vinculada.

• Escopo necessário: govbrempresa.

• Parâmetro: cnpj (query string) para filtrar uma empresa específica.

• Estrutura de dados: retorna o detalhamento do usuário com o cnpj.

• Aplicação prática: essencial para portais que exigem que o usuário atue em nome de uma empresa, garantindo que apenas representantes legais tenham acesso.

• Padrão de resposta: 200 OK em caso de sucesso. Se o usuário não possuir conta Gov.br vinculada ou não tiver empresas associadas, pode retornar 404 Not Found. Token inválido retorna 401 Unauthorized; escopo não autorizado retorna 403 Forbidden.

Níveis de Confiabilidade da Conta Gov.br

Os níveis de confiabilidade e demais atributos Gov.br são obtidos diretamente no retorno do UserInfo (/api/userinfo ou /api/v5/person), desde que a aplicação solicite os escopos correspondentes:

Os níveis de confiabilidade seguem as regras do Gov.br:

• Bronze (Nível 1): cadastro básico com validação de dados previdenciários.

• Prata (Nível 2): validação por reconhecimento facial ou credenciais bancárias.

• Ouro (Nível 3): validação por certificado digital ou base do TSE.

Relevância técnica: permite implementar controle de acesso granular; por exemplo, exigir nível Ouro para assinaturas digitais ou transações de alto risco.

3. Códigos de Resposta Comuns

4. Documentação Completa

Para consultar a especificação completa de todos os recursos, modelos de dados e demais entidades da API, acesse os Swaggers oficiais:

• Homologação: https://meu-api-hml.pub.hsm.rs.gov.br/api/docs

• Produção: https://logincidadao.rs.gov.br/api/docs

Dica de integração: durante o fluxo OIDC, utilize o endpoint de descoberta /.well-known/openid-configuration para obter dinamicamente os endpoints do provedor. Em cenários de migração, o userinfo_endpoint pode ser fixado para /api/v5/person para garantir compatibilidade com a nova estrutura de dados.