Authentication

API keys are used to authenticate against Principa Cloud APIs. See Create Credentials on how to create a Key and Secret for authentication.

All API requests must use HTTPS requests.

ⓘ Please keep API credentials, especially your Secret in a secure store. API keys can contain privileged roles.

Endpoint

All authentication is facilitated by the Security API. A successful authentication will return an accessToken which is used for subsequent calls to other API endpoints.

Environment	Base URL
Test	https://api.staging.principa.cloud/security/v1
Production	https://api.principa.cloud/security/v1

POST /authentication

Request Headers

Content-Type: application/json

Request Body

{
  "key": "your-client-key",
  "secret": "your-client-secret"
}

Field	Type	Required	Description
key	string	Yes	Your client key
secret	string	Yes	Your client secret

Successful Response

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpiresAt": "2025-05-07T15:00:00Z"
}

Field	Type	Description
success	boolean	true if authentication was successful
accessToken	string	The issued JWT access token
accessTokenExpiresAt	datetime	Expiry timestamp of the token
errorCode	string	(optional) Error code on failure
errorMessage	string	(optional) Human-readable error

Error Response

{
  "success": false,
  "errorCode": "INVALID_CREDENTIALS",
  "errorMessage": "Invalid authentication key or secret."
}

Security

This API uses the Bearer Authentication scheme.

Authorization: Bearer <access_token>

Use the returned accessToken in the Authorization header to access protected endpoints.

---

Continue: What is ADMiT? >>