API Authentication

All CRAFT API endpoints require authentication via JWT tokens issued by Keycloak. This page covers how to obtain tokens, authenticate requests, and handle token refresh.

Authentication Methods

User Tokens (OIDC)
Client Credentials
Development Tokens

For interactive applications, use the OIDC Authorization Code flow with PKCE:

Redirect the user to the Keycloak authorization endpoint
Exchange the authorization code for tokens
Include the access token in API requests

GET https://<keycloak-host>/realms/<org-id>/protocol/openid-connect/auth
  ?response_type=code
  &client_id=<client-id>
  &redirect_uri=<callback-url>
  &scope=openid email profile
  &code_challenge=<pkce-challenge>
  &code_challenge_method=S256

After the user authenticates, exchange the code:

curl -X POST \
  "https://<keycloak-host>/realms/<org-id>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<client-id>" \
  -d "code=<authorization-code>" \
  -d "redirect_uri=<callback-url>" \
  -d "code_verifier=<pkce-verifier>"

For service accounts, CI/CD pipelines, and automation, use the client credentials grant:

curl -X POST \
  "https://<keycloak-host>/realms/<org-id>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<service-account-id>" \
  -d "client_secret=<service-account-secret>"

Response:

{
  "access_token": "<jwt-access-token>",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "openid email profile"
}

Client credentials tokens do not include a refresh token. Obtain a new access token before expiration.

For local development, use the make get-token shortcut in the em-runtime repository:

# Get a token for the org admin user
make get-token

# Get a platform admin token (Keycloak master realm)
make get-platform-token

Or use curl directly:

TOKEN=$(curl -s -X POST \
  "http://localhost:8080/realms/<org-id>/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin" \
  | jq -r '.access_token')

The password grant is intended for development only. Never use it in production — use OIDC with PKCE or client credentials instead.

Using the Token

Include the access token in the Authorization header of every API request:

curl -X GET "https://<platform-host>/api/governance/organizations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <project-id>"

Required Headers

Header	Required	Description
`Authorization`	Always	`Bearer <access-token>`
`X-Project-ID`	Most endpoints	UUID of the target project
`Content-Type`	Write operations	`application/json`

The X-Project-ID header determines which project the request is scoped to. A single JWT token can access multiple projects within the same organization. The project ID is never embedded in the JWT.

Token Refresh

Access tokens have a short lifetime (typically 5 minutes). Use the refresh token to obtain new access tokens without re-authentication:

curl -X POST \
  "https://<keycloak-host>/realms/<org-id>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=<client-id>" \
  -d "refresh_token=<refresh-token>"

Refresh Strategy

Monitor token expiry

Track the exp claim in the JWT payload. Plan to refresh when 75% of the token lifetime has elapsed.

Proactive refresh

Refresh the token before it expires to avoid 401 errors during in-flight requests.

Handle refresh failure

If the refresh token is expired or revoked, redirect the user to the login flow. For service accounts, obtain a new token via client credentials.

SDK Authentication

The auto-generated SDKs follow the openapi-python-client and openapi-generator patterns — an AuthenticatedClient with a token constructor arg + per-endpoint module functions, not an object/fluent client. See the Python SDK and TypeScript SDK overviews for the full client model.

Python
TypeScript

from em_runtime_governance_sdk import AuthenticatedClient
from em_runtime_governance_sdk.api.organizations import list_organizations

client = AuthenticatedClient(
    base_url="https://<platform-host>/api/governance",
    token=access_token,
)
orgs = await list_organizations.asyncio(client=client)

# Token refresh: pop the expired client and rebuild with a fresh token.
# The SDK has no built-in onTokenExpired callback; wrap your calls in a
# helper that catches 401, refreshes, and retries with a new client.

import { Client } from '@emergence-ai/em-runtime-governance-sdk';
import { listOrganizations } from '@emergence-ai/em-runtime-governance-sdk/api';

const client = new Client({
  BASE: 'https://<platform-host>/api/governance',
  TOKEN: accessToken,
});
const orgs = await listOrganizations({ client });

Token Claims

The JWT access token contains these claims used by the platform:

{
  "sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "iss": "https://keycloak.example.com/realms/org-123",
  "aud": "emergence-platform",
  "exp": 1712150400,
  "iat": 1712150100,
  "groups": ["admins", "developers"],
  "email": "user@example.com",
  "preferred_username": "jdoe"
}

Claim	Platform Usage
`sub`	Unique user identifier for audit logs
`iss`	Organization ID derived from realm in the issuer URL
`groups`	Mapped to OpenFGA roles for permission checks
`exp`	Token expiration validation

Error Responses

Authentication failures return structured error responses:

Status	Code	Description
`401`	`UNAUTHENTICATED`	No token provided or token signature invalid
`401`	`TOKEN_EXPIRED`	Access token has expired; refresh and retry
`403`	`FORBIDDEN`	Token is valid but user lacks permission for this operation
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests; check `Retry-After` header

Next Steps

API Overview

Review the full API structure, endpoints, and rate limits.

Error Codes

Understand all error response formats and troubleshooting steps.

SSO Integration

Configure SSO for enterprise identity providers.

RBAC Configuration

Set up roles and permissions for API access control.

Overview

Platform APIs

Solution APIs

SDKs & Client Libraries

API Authentication

API Authentication

Authentication Methods

Using the Token

Required Headers

Token Refresh

Refresh Strategy

SDK Authentication

Token Claims

Error Responses

Next Steps

API Overview

Error Codes

SSO Integration

RBAC Configuration

​API Authentication

​Authentication Methods

​Using the Token

​Required Headers

​Token Refresh

​Refresh Strategy

​SDK Authentication

​Token Claims

​Error Responses

​Next Steps

API Overview

Error Codes

SSO Integration

RBAC Configuration

API Authentication

Authentication Methods

Using the Token

Required Headers

Token Refresh

Refresh Strategy

SDK Authentication

Token Claims

Error Responses

Next Steps