Skip to main content

Authentication API

Obtaining an Authentication Token​

To access any of Promethium’s APIs, you must first authenticate using your Promethium credentials. This API issues an id_token that must be included in the idtoken header for all subsequent API calls. The process differs depending on whether your user is manged externally to Promethium (SSO) or locally.

SSO User​

Obtaining an authentication token for an SSO users is performed interactively via the user’s browser via a GET request to https://api.prod.promethium.ai/auth/login/{tenant}. {tenant} refers to the following in the application URL: https://{tenant}.prod.promethium.ai. You will be directed to your SSO provider. After a successful login, the browser will redirect to Promethium’s OAuth2 callback URL, with a JSON response in the response format;

{
 "refresh_token": "***",
 "access_token": "***",
 "id_token": "***",
 "expires_in": 3600,
 "token_type": "Bearer"
 }

The id_token field will be used for authentication to subsequent APIs in the header idtoken.

Local Service Account​

Local service account authentication is performed via a POST request to the login endpoint. On success, you will receive:

  • id_token: Used in the idtoken header for authenticating API requests
  • access_token: Used internally by Promethium services
  • refresh_token: Used to obtain new id_token and access_token when they expire

🔐 Example: curl​

curl -X POST https://api.prod.promethium.ai/auth/login/{tenant} \
  -H "Content-Type: application/json" \
  --data '{
    "email": "your-service-account@your-organisation.com",
    "password": "your_password"
  }'

On successful authentication, the API will respond with JSON in the response format

{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eI3h3H9rKJY6LsX0e..."
}

✅ Use the id_token value in the idtoken header for all subsequent API calls.

Refresh token​

Tokens are short-lived for security reasons. You can use the refresh_token to re-issue a new id_token and access_token without requiring the password again.

Endpoint​

POST https://api.prod.promethium.ai/auth/refresh/{tenant}

Request Body​

refresh_token=<authentication_refresh_token>

Logout / Revoke Token​

To revoke an active session or sign out of Promethium, open the following URL in your browser:

https://api.prod.promethium.ai/auth/logout/{tenant}

This will invalidate the current session and redirect the user to the login screen.