Guia de Autenticação e Acesso Seguro

Este documento descreve o processo de obtenção de credenciais, negociação de chaves e autenticação para acesso aos serviços da plataforma de governo digital.

1. Obtenção de Credenciais

Antes de iniciar a integração técnica, sua organização deve solicitar o acesso formalmente:

1. Acesse o formulário: Solicitar Acesso - GovPi Conecta.
2. Após a aprovação, você receberá um conjunto de credenciais contendo:
   • App-Key: Identificador único da sua aplicação (deve ser enviado em todas as requisições via header).
   • Client ID: Usuário de integração.
   • Client Secret: Chave secreta de integração.

Importante: A App-Key deve ser incluído no header de todas as chamadas: app-key: SUA_APP_KEY.

---

2. Fluxo de Autenticação (Passo a Passo)

Passo 1: Geração de Chaves e Handshake

Após instalar a biblioteca EncryptoO, gere seu par de chaves e realize a troca com o serviço de segurança.

// 1. Gerar chave pública local
import Encryptoo from 'encryptoo';
const localPublicKey = Encryptoo.init();

Endpoint: POST https://api.pidigital.pi.gov.br/v1/api-security/security/change-keys
Headers: app-key: SUA_APP_KEY

// 2. Realizar a troca de chaves com o serviço de segurança
const response = await fetch('https://api.pidigital.pi.gov.br/v1/api-security/security/change-keys', {
  method: 'POST',
  headers: {
    'app-key': 'SUA_APP_KEY',
  },
  body: { clientPublicKey: localPublicKey }
});

const serverPublicKey = response.data.serverPublicKey;
const xAccessToken = response.data["x-access-token"];

O x-access-token recebido será utilizado apenas para a próxima etapa de login.

Passo 2: Login Criptografado (Keycloak)

Nesta etapa, você utilizará a serverPublicKey obtida no passo anterior para proteger suas credenciais sensíveis antes do envio. Endpoint: POST https://api.pidigital.pi.gov.br/v1/login/auth/login-keycloack
Headers:

• app-key: SUA_APP_KEY
• Authorization: Bearer ${x-access-token}

// 3. Criptografar credenciais com a chave do servidor
const encryptedCredentials = {
  client_id: EncryptoO.Encrypt('SEU_CLIENT_ID', serverPublicKey),
  client_secret: EncryptoO.Encrypt('SEU_CLIENT_SECRET', serverPublicKey)
};

// 4. Realizar o login final
const authResponse = await axios.post('https://api.pidigital.pi.gov.br/v1/login/auth/login-keycloack', 
    encryptedCredentials, 
    {
      headers: { 
        'app-key': 'SUA_APP_KEY',
        'Authorization': `Bearer ${x-acess-token}`
      }
    }
);

const { access_token } = authResponse.data;

3. Uso do Access Token

O access_token final recebido no Passo 2 é o token de longa duração que deve ser utilizado para consumir os dados do Datalake e outros serviços protegidos, sempre acompanhado da sua app-key.

4. Resumo de Headers Obrigatórios

Etapa	Header app-key	Header Authorization
Handshake	Obrigatório	Não necessário
Login	Obrigatório	Bearer JWT_INTERMEDIARIO
Consumo de APIs	Obrigatório	Bearer ACCESS_TOKEN