Overview

Authentication

Copy page

To use the Compliance Assessment 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/compass/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 an 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.

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/compass/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>"

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.