Integração com a RA API

Visão geral

Este guia descreve o fluxo de integração com a RA API do Redtrust: autenticação, emissão e renovação de certificados. É voltado para desenvolvedores de parceiros com capacidade para emitir certificados.

Autenticação

A RA API suporta dois mecanismos de autenticação.

Login direto

Autenticação servidor a servidor via POST /raapi/v1/auth/login com as credenciais do usuário de aplicação. Retorna um accessToken e um refreshToken.

Consulte o endpoint completo na referência da RA API.

Redirecionamento HMAC

Fluxo de redirecionamento para integrações em que o usuário se autentica por meio da interface web do Redtrust. O navegador é redirecionado para:

https://SEU_IP_REDTRUST:PORTA/authclient/auth/loginrequest?Consumer=RA_API&Domain=SEU_DOMÍNIO&RedirectUrl=URL_REDIRECIONAMENTO&timestamp=TIMESTAMP&partner=NOME_PARCEIRO&hmac=ASSINATURA_HMAC

Onde:

• SEU_IP_REDTRUST é o endereço IP ou o nome do host do servidor Redtrust.
• PORTA é a porta de acesso ao serviço (padrão 8082).
• SEU_DOMÍNIO é o domínio dos usuários (opcional).
• URL_REDIRECIONAMENTO é a URL de retorno após a autenticação. Aplique UrlEncode.
• TIMESTAMP é o timestamp no formato UNIX.
• NOME_PARCEIRO é o nome da aplicação cliente em maiúsculas.
• ASSINATURA_HMAC é a assinatura HMAC-SHA256 gerada com a chave compartilhada.

Após a autenticação, o Redtrust redireciona para a URL configurada com um token temporário no parâmetro tkn. Este token deve ser trocado por um token de acesso via POST /authapi/v1/login_by_temp_token. Consulte o endpoint na referência da RA API.

Em ambos os casos, o accessToken obtido é incluído como Bearer token em todas as chamadas aos endpoints protegidos.

Emissão de certificados

A emissão requer duas chamadas consecutivas:

1. POST /raapi/v1/csr/create — gera o par de chaves no servidor e retorna o CSR e um requestCode.
2. PUT /raapi/v1/csr/finalize — conclui a emissão usando o requestCode. Retorna o idCertificate e o thumbprint do certificado emitido.

O campo provider na chamada a POST /raapi/v1/csr/create identifica o provedor de certificados. Consulte a documentação do provedor para conhecer o valor correto.

Consulte a descrição completa de ambos os endpoints na referência da RA API. Para um exemplo completo com a Camerfirma, consulte o tutorial Integração com a Camerfirma.

Renovação de certificados

O fluxo de renovação usa os mesmos endpoints que a emissão. A única diferença é o campo thumbprintToRenew no body de POST /raapi/v1/csr/create, que identifica o certificado a ser renovado. O novo certificado substitui o anterior e preserva sua configuração e associações.