Authentication

Overview

Authentication to our APIs is based on the OAuth 2.0 Client Credentials Grant. External systems authenticate directly with our identity provider — without end-user involvement — to obtain an access token required for all API calls.

The authentication process consists of two steps:

1. Obtain an access token by calling our OAuth 2.0 token endpoint with your client credentials.
2. Call APIs by including the access token as a Bearer token in the Authorization header of every request.

---

Step 1: Requesting an Access Token

Endpoint

Environment	URL
Test	https://keycloak-test.playground.venistar.com/realms/master/protocol/openid-connect/token

note

The endpoint above refers to the test environment. A separate endpoint is provided for the production environment; please refer to your onboarding documentation or contact your API administrator for the corresponding production URL.

HTTP Method

POST

Request Parameters

The token endpoint expects a request with Content-Type: application/x-www-form-urlencoded and the following body parameters:

Parameter	Value	Description
grant_type	client_credentials	Fixed value. Identifies the OAuth 2.0 flow used to obtain the token.
client_id	(provided by the API administrator)	The unique identifier assigned to your client application.
client_secret	(provided by the API administrator)	The confidential secret associated with your client_id. Must be kept secure and never exposed publicly.

warning

The client_id and client_secret are unique credentials issued by the API system administrator during the onboarding process. They must be treated as sensitive information and stored securely (e.g., in a secrets manager or encrypted configuration), never hard-coded in source code or shared in plain text.

Example Request

curl -X POST "https://keycloak-test.playground.venistar.com/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Example Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia...",
    "expires_in": 3600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

Token Expiration

Environment	Token Lifetime
Test	1 hour (expires_in: 3600 seconds)

Once the token expires, any API call authenticated with it will be rejected. The client application must request a new access token by repeating the call to the token endpoint described above.

tip

Client applications should cache the access token and reuse it for subsequent API calls until it is close to expiration, rather than requesting a new token for every single API call. This reduces unnecessary load on the authentication server and improves performance.

---

Step 2: Calling the APIs

Once the access token has been obtained, it must be included in the Authorization header of every request made to our APIs, using the Bearer scheme.

Header Format

Authorization: Bearer <access_token>

Example API Call

curl -X GET "https://api.example.com/v1/resource" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ..."

If the token is missing, invalid, or expired, the API will return an HTTP 401 Unauthorized response.

---

Summary Flow

1. External system sends a POST request to the token endpoint with grant_type, client_id, and client_secret.
2. Identity provider validates the credentials and returns an access_token (valid for 12 hours in the test environment).
3. External system includes the access_token in the Authorization: Bearer header for all subsequent API requests.
4. When the token expires, the external system repeats step 1 to obtain a new token.

---

Obtaining Credentials

To obtain your client_id and client_secret, please contact the API system administrator. Credentials are issued per client application and should not be shared between multiple systems or environments.