API Authentication | OCP® Learning Center

Authentication Requirements

To ensure secure access to our API, all endpoints require authorization through a Bearer Token or a Personal Access Token (PAT)

Bearer Token Authentication

Include the following headers in your HTTP requests to authenticate:

Authorization: Bearer {{Token}}

Here’s an example command using cURL:

Bash

curl -X GET \
  -H "Authorization: Bearer {{Token}}" \
  https://example.com/api/your-endpoint

Replace {{Token}} with the actual Bearer token obtained through the authentication process.

Ensure the token is included in the Authorization header for every request, to successfully authenticate and access the API endpoints.

Keep your tokens secure and never expose them in public repositories or insecure environments.

Authorization Token Endpoint

Overview

This section outlines the process of obtaining a Bearer authorization token from OCP’s IAM.

Please replace dynamic parts such as the base URL, username, and password with the appropriate values enclosed in double curly brackets (for example, {{Host}}, {{Username}}, {{Password}}).

Endpoint details

Obtaining an Access Token

To authenticate with the API, you first need to obtain an access token by making a request to the token endpoint as shown in the example below. The response will include both an access_token and a refresh_token.

Hosts and Authentication Endpoints

Host	Base URL	Authentication Endpoint
Swarm Environments
EU1	https://eu1-m.ocp.ai	`/auth/realms/master/protocol/openid-connect/token`
US1	https://us1-m.ocp.ai
US2	https://auth.us2-m.ocp.ai
K8s Environments
CA1	https://pub.ca1.ocp.ai	`/auth/realms/ocp/protocol/openid-connect/token`
FRANKFURT	https://pub.frankfurt.ocp.ai	`/auth/realms/ocp/protocol/openid-connect/token`

Headers

Paramenter	Value
`Content-Type`	`application/x-www-form-urlencoded`

Body

Parameter	Description	Value
`client_id`	The client ID	ocp
`grant_type`		password
`username`	The OCP Username	{{Username}}
`password`	The OCP Password	{{Password}}
`otp` (or `totp`)	2FA	{{2FA_Code}}

Note that otp is mandatory for all OCP environments starting 2026-01-20. Also read the corresponding guide in Logging in and logging out | Two-Factor Authentication.

Example Request

Bash

curl --location --request POST '{{Host}}/{{HostEndPoint}}' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'client_id=ocp' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'username={{Username}}' \
     --data-urlencode 'password={{Password}}' \
     --data-urlencode 'otp={{2FA_Code}}'

Example Response

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgO...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgO...",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "6d4e82a1-2d6d-402a-9d52-f3f99d7a477c",
  "scope": "openid"
}

The access_token will be required in any later API request for authorization.

Error Responses

If there is an issue with the request, OCP’s IAM will respond with an appropriate error message. Common error responses include:

Response	Reason
`Invalid Grant`	The provided credentials (username/password) are incorrect.

Session limit

Given the five-sessions limit in some environments, it is crucial to log out sessions when they are no longer needed.

Logging out helps to manage your sessions efficiently and stay within the session limit imposed by your environment.

You can log out by making a request to the logout endpoint using the refresh_token obtained earlier from the response of the token request.

Here is an example request:

Bash

curl -X POST "{{Host}}/auth/realms/master/protocol/openid-connect/logout" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=ocp" \
     -d "refresh_token=$REFRESH_TOKEN"

Personal Access Token (PAT) Authentication

Personal Access Tokens are intended for automated scripts, CI/CD pipelines, and integrations where interactive OAuth2 login is not feasible.

To create a Personal Access Token, read the Access Management Tab | Personal Tokens guide.
Replace the Authorization header with the following in any subsequent requests:
X-OCP-PERSONAL-ACCESS-TOKEN: {{your_pat_here}}

When using a PAT, the system automatically upgrades the request context by injecting the generated JWT into the Authorization header. This ensures that subsequent microservices or internal logic can treat the request as a standard Bearer-authenticated call.

PAT API limitations

PAT is supported only by the following services:

Metrics-API
Exports-API
miniApps spring-API
Testing Studio
Orchestrator
NLU
Environments Manager

Using PAT will result in account deactivation if the account is inactive for 90 days.

Users must log in through the OCP UI or script within this period to avoid account deactivation.

Account deactivation requires a new PAT after reactivation.

Security Considerations

Ensure that the communication with the OCP’s IAM service is over HTTPS to secure the transmission of sensitive information.

Protect your username and password as sensitive information and avoid hardcoding them in your application code.

Implement secure storage and transmission practices for the obtained access token.