Sign API

Overview

The Redtrust Sign API is a REST API that lets you integrate document signing using digital certificates managed centrally in Redtrust. It is designed for external applications that need to authenticate users, retrieve their certificates, perform signing operations, and manage the user's signature profile.

Base URL

https://YOUR_REDTRUST_IP:PORT/signapi

The default port is 8083. For example: https://localhost:8083/signapi/v1/certificate/list.

Authentication

Access token

All Sign API endpoints require an access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

There are two ways to obtain that token, depending on your integration type:

Sign Service login flow

This is the flow described in detail in Sign Service integration. In summary:

1. Your application redirects the user to GET /authclient/auth/loginrequest with the partner parameters (including the HMAC signature).
2. The user authenticates in Redtrust (or in their external identity provider).
3. Redtrust redirects the user to your callback URL with a temporary token (tkn).
4. Your application exchanges that temporary token for an access token by calling POST /authapi/v1/login_by_temp_token.

OAuth2 authorization code flow

This is the standard OAuth2 flow. It follows the same redirect pattern but uses the standard endpoints:

1. Your application redirects the user to GET /authclient/authorize with client_id, redirect_uri, response_type=code, state, and the PKCE parameters (code_challenge and code_challenge_method).
2. The user authenticates.
3. Redtrust redirects the user to your callback URL with an authorization code (code).
4. Your application exchanges that code for an access token by calling POST /authclient/token.

In both cases, the result is an access token that you include in the Authorization header of all Sign API calls.

tip

The OAuth2 flow is the recommended approach for new integrations, as it follows a widely adopted standard and allows session renewal with a refresh token.

warning

Prerequisite: the OAuth2 flow only works if the Redtrust administrator has already registered your redirect URI. See Configure the redirect URIs.

OAuth2 flow parameters

This flow implements PKCE (Proof Key for Code Exchange) to prevent authorization code interception attacks.

Authorization request

GET /authclient/authorize

Parameter	Required	Description
response_type	Yes	Must be code.
client_id	Yes	Your application identifier. Redtrust assigns this value when you register your application.
redirect_uri	Yes	The URL to which Redtrust redirects the user after authentication. Must exactly match one of the redirect URIs registered for the service in the admin console.
code_challenge	Yes	PKCE challenge derived from the code_verifier. Between 43 and 128 characters in base64url format.
code_challenge_method	Yes	Challenge transformation method. The only supported value is S256.
state	Yes	Random value your application generates to prevent CSRF attacks. Between 16 and 512 characters. Redtrust returns it unchanged in the redirect.
domain	No	The user's domain. If omitted, the user can select it during authentication.

Code-for-token exchange

POST /authclient/token with an application/x-www-form-urlencoded body:

Parameter	Required	Description
grant_type	Yes	Must be authorization_code.
client_id	Yes	The same client_id from the authorization request.
redirect_uri	Yes	The same redirect URL from the authorization request.
code	Yes	The authorization code received in the redirect.
code_verifier	Yes	The original PKCE code_verifier your application generated before computing the code_challenge.

The server responds with:

{
  "access_token": "...",
  "token_type": "Bearer",
  "refresh_token": "..."
}

Token refresh

When the access token expires, you can renew it without requiring the user to authenticate again. Call POST /authclient/token with:

Parameter	Required	Description
grant_type	Yes	Must be refresh_token.
client_id	Yes	Your application identifier.
refresh_token	Yes	The refresh token received in the previous response.

HMAC headers

In addition to the access token, each Redtrust installation can require HMAC headers to validate the partner's identity on every API call. If enabled, include them in all requests:

Header	Description
x-partner-name	The client application name in uppercase. Used to identify and authorize the calling partner.
x-request-timestamp	UNIX timestamp indicating when the request is made. Helps prevent replay attacks.
x-hmac-signature	HMAC-SHA256 signature generated by signing the message PARTNER_NAME:UNIX_TIMESTAMP with the shared secret key.

HMAC validation can be disabled from the installation configuration. Check with your Redtrust administrator whether your integration requires it.

Response format

All endpoints return the following JSON structure:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "string",
  "data": {}
}

Field	Description
message	Descriptive message about the result.
messageType	SUCCESS if the operation completed successfully; ERROR if a problem occurred.
errorCode	An error identifier code, or OK when the operation succeeds.
data	Response content. The type varies by endpoint — it can be an object, a list, or empty.