Autenticação v5 (mTLS)

A Plataforma de Crédito Celcoin utiliza o protocolo OAuth 2.0, com o fluxo client_credentials, para autenticação e autorização das requisições realizadas às APIs de Crédito.

Para reforçar a segurança das integrações, a Celcoin adotou um novo modelo de autenticação, que combina credenciais V5, certificado digital mTLS (Mutual TLS) e validação do IP de origem.

Importante: todos os novos clientes de Crédito devem iniciar suas integrações utilizando o modelo de autenticação V5, com certificado mTLS e IP de origem previamente autorizado.

1. Requisitos para integração

Antes de iniciar a integração com as APIs de Crédito, é necessário atender aos seguintes requisitos:

Os três requisitos fazem parte do modelo de segurança adotado para novas integrações.

2. Como funciona a autenticação

O processo de autenticação contempla a validação dos requisitos de segurança e a obtenção de um token de acesso.

Etapa 1 — Habilitação das credenciais

O cliente solicita à Celcoin as credenciais V5 necessárias para utilização das APIs de Crédito.

Etapa 2 — Configuração do certificado mTLS

O cliente configura o certificado digital disponibilizado ou autorizado pela Celcoin em seu ambiente de integração.

O mTLS (Mutual Transport Layer Security) permite a autenticação mútua durante o estabelecimento da conexão segura, adicionando uma camada de proteção à comunicação.

Etapa 3 — Autorização do IP de origem

O cliente informa os endereços IP públicos e fixos utilizados nas requisições. Esses endereços devem estar previamente autorizados pela Celcoin.

Etapa 4 — Solicitação do token

Após a habilitação dos requisitos, o cliente realiza a requisição de autenticação utilizando suas credenciais V5, por meio do fluxo OAuth 2.0 client_credentials.

Etapa 5 — Utilização do token

O token de acesso obtido deve ser informado no header Authorization das requisições realizadas às APIs de Crédito, utilizando o prefixo Bearer.

3. Como solicitar a habilitação

Para iniciar uma nova integração, entre em contato com o Key Account Manager ou responsável pelo onboarding na Celcoin.

Durante o processo de habilitação, será necessário:

1. Solicitar as credenciais V5 para a API de Crédito.
2. Informar os endereços IP públicos e fixos utilizados na integração.
3. Seguir as orientações da Celcoin para emissão, disponibilização ou configuração do certificado mTLS.
4. Configurar os requisitos de autenticação no ambiente de integração.
5. Validar a conectividade e a obtenção do token antes de iniciar as chamadas às APIs de Crédito.

Atenção: a utilização das APIs depende da conclusão das configurações de segurança aplicáveis ao ambiente.

4. Obtenção do token de acesso

A API de Crédito utiliza o protocolo OAuth 2.0, com o fluxo client_credentials + certiicado mTLS, para obtenção do token de acesso.

Após a habilitação das credenciais e a configuração dos requisitos de segurança, o cliente poderá realizar a requisição de autenticação.

Parâmetros da requisição

As credenciais client_id e client_secret são utilizadas no header HTTP Authorization, com o prefixo Basic, conforme o padrão de autenticação OAuth 2.0 documentado pela Celcoin.

O valor enviado deve corresponder à codificação Base64 da combinação client_id:client_secret.

Exemplo de requisição

O exemplo abaixo demonstra a estrutura da solicitação de token com autenticação Basic e certificado de cliente. Os endereços e arquivos devem ser substituídos pelos dados homologados para sua integração.

curl --request POST \
  --url '<URL_DE_AUTENTICACAO_V5>' \
  --cert '<CAMINHO_CERTIFICADO_CLIENTE>' \
  --key '<CAMINHO_CHAVE_PRIVADA>' \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --user '<CLIENT_ID>:<CLIENT_SECRET>' \
  --data-urlencode 'grant_type=client_credentials'

Observações:

• O exemplo utiliza arquivos separados para o certificado e a chave privada.
• A configuração do certificado pode variar conforme o formato disponibilizado e a tecnologia utilizada pelo cliente.
• O endereço do servidor de autenticação deve corresponder ao ambiente e ao modelo de autenticação habilitados pela Celcoin.
• Os arquivos de certificado e chave privada não devem ser compartilhados publicamente.

5. Utilização do token nas APIs de Crédito

Após a autenticação bem-sucedida, o servidor retorna um token de acesso que deverá ser utilizado nas requisições subsequentes.

O token deve ser informado no header HTTP Authorization, precedido pelo prefixo Bearer.

Exemplo

Authorization: Bearer <ACCESS_TOKEN>

O token permite que a aplicação realize requisições autenticadas às APIs de Crédito, respeitando as permissões associadas às credenciais utilizadas.

Validade do token

Conforme a documentação de autenticação da Plataforma de Crédito, o token possui validade de 3.600 segundos (60 minutos).

Não é necessário solicitar um novo token a cada requisição. A aplicação deve controlar a validade do token e solicitar um novo quando necessário.

6. Requisitos de segurança

Certificado mTLS

O certificado mTLS é utilizado como mecanismo adicional de autenticação na comunicação entre o cliente e a Celcoin. Mais detalhes em https://developers.celcoin.com.br/docs/mtls

Para estabelecer a conexão, o cliente deve configurar corretamente o certificado e sua respectiva chave privada, conforme as orientações recebidas durante a habilitação.

A utilização de credenciais válidas não substitui a necessidade de configuração do certificado mTLS.

IP de origem autorizado

As requisições devem ser realizadas a partir dos endereços IP previamente autorizados.

Caso o cliente utilize mais de um IP de saída, todos os endereços necessários deverão ser informados à Celcoin para avaliação e autorização.

Alterações nos endereços IP utilizados na integração devem ser comunicadas à Celcoin para atualização das configurações de acesso.

Proteção das credenciais

Para garantir a segurança da integração, recomenda-se:

• Armazenar credenciais e chaves privadas em mecanismos seguros de gerenciamento de segredos.
• Não incluir credenciais, tokens ou chaves privadas em códigos-fonte, repositórios públicos ou logs.
• Restringir o acesso às credenciais e aos certificados às aplicações e pessoas autorizadas.
• Acompanhar a validade dos certificados e realizar as atualizações necessárias antes do vencimento.
• Utilizar conexões HTTPS nas comunicações com a plataforma.

7. Problemas de autenticação

Caso a aplicação não consiga obter o token ou realizar requisições autenticadas, verifique os seguintes cenários:

Caso o problema persista, entre em contato com o suporte da Celcoin, informando o ambiente utilizado, o horário da ocorrência e os detalhes técnicos necessários para análise, sem compartilhar credenciais ou chaves privadas.

8. Clientes com integrações existentes

Clientes que já utilizam as APIs de Crédito por meio do modelo anterior de autenticação deverão seguir o processo de migração para V5, conforme as orientações e o planejamento disponibilizados pela Celcoin.

A migração poderá envolver atualização de credenciais, configuração do certificado mTLS e autorização dos endereços IP utilizados na integração.

Novas integrações devem utilizar diretamente o modelo V5 com mTLS e IP autorizado.

9. Suporte e documentação complementar

Para dúvidas sobre habilitação de credenciais, configuração de certificados ou autorização de IPs, entre em contato com o responsável pelo onboarding ou com o suporte da Celcoin.