RA API integration

Overview

In this guide, you learn how to integrate with the RA API to manage the complete certificate lifecycle: authenticating users, generating CSRs on the Redtrust server, and issuing and renewing digital certificates.

This guide is intended for developers at Redtrust partners with certificate issuance capabilities. To follow it, you need basic knowledge of HTTP APIs, bearer token authentication, and digital certificates.

Before you start

To integrate the service, you need the following information provided by the Redtrust client:

• IP address or host name of the Redtrust server.
• The port used to access the service (the default value is 8082).
• Application username for the service.
• (Optional) Domain name.

If you use the HMAC redirect flow, you also need:

• A redirect URL where Redtrust sends the temporary token after authentication. This address must be registered in Redtrust by an admin before you start.

Step 1: Get an access token

The RA API supports two authentication methods. Choose the one that fits your integration.

Direct login

Use this option for server-to-server integrations and Postman testing.

Send a POST request to /raapi/v1/auth/login with the user's credentials:

POST /raapi/v1/auth/login

{
  "username": "string",
  "password": "string",
  "domain": "string"
}

The response includes the accessToken and refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Use the accessToken in all subsequent requests. Proceed to Step 2.

HMAC redirect

Use this option when users authenticate through Redtrust's web interface.

The Certificate Enroll redirect flow uses the same HMAC mechanism as the Sign API, with one difference: the Consumer parameter must be RA_API.

Redirect the user's browser to:

https://YOUR_REDTRUST_IP:PORT/authclient/auth/loginrequest?Consumer=RA_API&Domain=YOUR_DOMAIN&RedirectUrl=REDIRECT_URL&timestamp=TIMESTAMP&partner=PARTNER_NAME&hmac=HMAC_SIGNATURE

Where:

• YOUR_REDTRUST_IP is the IP address or host name of your Redtrust server.
• PORT is the port used to access the service (default 8082).
• YOUR_DOMAIN is the users' domain (optional).
• REDIRECT_URL is the URL to redirect to after authentication. Apply UrlEncode.
• TIMESTAMP is the timestamp in UNIX format.
• PARTNER_NAME is the client application name in uppercase.
• HMAC_SIGNATURE is the HMAC-SHA256 signature generated with the shared key.

If authentication completes successfully, Redtrust redirects the user's browser to your redirect URL:

https://YOUR_REDIRECT_URL/TEMPORARY_TOKEN

Exchange the temporary token

Intercept the tkn parameter from the redirected URL. Your application must then make a server-side call to exchange it for a permanent access token:

POST /authapi/v1/login_by_temp_token

{
  "temporalToken": "YOUR_TEMPORARY_TOKEN"
}

Where YOUR_TEMPORARY_TOKEN is the value of the tkn parameter from the redirect URL.

The response includes the accessToken and refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Use the accessToken to authenticate all calls to the RA API. Proceed to Step 2.

Step 2: Issue a certificate

To issue a certificate, call two endpoints in sequence.

1. Create the CSR

POST https://YOUR_REDTRUST_IP:PORT/raapi/v1/csr/create

Where YOUR_REDTRUST_IP and PORT are the address and port of your Redtrust server.

See the full endpoint description, including body fields and examples, in the RA API reference.

The server returns a CSR and a requestCode. Save the requestCode — you need it in the next step.

2. Finalize the issuance

PUT https://YOUR_REDTRUST_IP:PORT/raapi/v1/csr/finalize

See the full endpoint description in the RA API reference.

Step 3: Renew a certificate

The renewal flow uses the same endpoints as issuance. The only difference is that you must include the thumbprintToRenew field in the body of the call to POST /raapi/v1/csr/create:

{
  "...": "...",
  "thumbprintToRenew": "THUMBPRINT_OF_CERTIFICATE_TO_RENEW"
}

Where THUMBPRINT_OF_CERTIFICATE_TO_RENEW is the thumbprint of the existing certificate you want to renew.

After creating the CSR, call the same finalization endpoint (PUT /raapi/v1/csr/finalize) with the requestCode obtained. The new certificate replaces the previous one, preserving its configuration and associations.

See the full description of both endpoints in the RA API reference.