Compliance Assessment Service LogoCompliance Assessment Service
Overview

Authentication

To use the Compliance Assessnent Service, you must authenticate your application using OAuth2. The API uses short-lived access tokens to authorize requests. This section describes how to obtain these tokens securely using our identity provider.

Obtaining an Access Token

To acquire an access token, clients must authenticate against the Keycloak token endpoint using the Resource Owner Password Credentials (ROPC) grant type. This is typically used in trusted applications (e.g. CLI tools, backend services) where the application itself handles user credentials.

Code
 
curl -X POST https://compliance-assessment.precognox.com/keycloak/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com" \
  -d "password=password123" \
  -d "client_id=your-api-client" \
  -d "client_secret=your-client-secret" \
  -d "grant_type=password"

Required Parameters

The following parameters must be sent as a application/x-www-form-urlencoded payload:

  • username: The user's login username.
  • password: The corresponding password.
  • client_id: The client identifier registered in Keycloak.
  • client_secret: The secret associated with the client.
  • grant_type: Must be set to password.

Response

Code
 
{
  "access_token": "<jwt-access-token>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<jwt-refresh-token>",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "<session-id>",
  "scope": "profile email"
}
  • access_token: JWT used to authorize requests.
  • refresh_token: Used to obtain new tokens without re-authenticating.
  • expires_in: Token lifespan in seconds.

Access tokens expire after 300 seconds (5 minutes).

Store tokens securely, never expose them.

Making Authenticated API Requests

All API endpoints require a valid access token in the Authorization header:

Code
 
Authorization: Bearer <access_token>

The server validates the token using public keys (via JWKS), verifies the token’s signature, expiration, and scopes/roles.

Refreshing Tokens

When the access token expires, the client can use the refresh_token to obtain a new access_token without requiring the user to log in again.

Token Refresh Request

Code
 
curl -X POST https://compliance-assessment.precognox.com/keycloak/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=your-api-client" \
  -d "client_secret=your-client-secret" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<your-refresh-token>"
  • The refresh_token is valid for a longer period than the access token
  • The response contains a new access_token and a new refresh_token
  • Refresh tokens must be stored and managed securely by the application
  • Do not use expired tokens: always check the validity of the token and refresh it in a timely manner

Client Registration

To use the Compliance Assessment Service, each partner requires a unique client ID, secret, and authentication credentials. These are provided as part of the technical integration process once the contract is in place. We create the necessary user accounts, client identifiers, and secrets, and deliver them securely to support the start of the integration.

Last modified on
Getting Started