Documentation Index Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
Use this file to discover all available pages before exploring further.
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" : "eyJhbGciOiJSUzI1NiIs..." , "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://<host>:8001/governance/organizations" \ -H "Authorization: Bearer $TOKEN " \ -H "X-Project-ID: <project-id>"
Header Required Description AuthorizationAlways Bearer <access-token>X-Project-IDMost endpoints UUID of the target project Content-TypeWrite 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 handle token management:
from em_runtime_governance_sdk import GovernanceClient # Direct token client = GovernanceClient( base_url = "https://<host>:8001" , token = access_token ) # With automatic token refresh client = GovernanceClient( base_url = "https://<host>:8001" , token_provider = my_token_provider # Callable that returns fresh tokens )
import { GovernanceClient } from '@emergence/em-runtime-governance-sdk' ; const client = new GovernanceClient ({ baseUrl: 'https://<host>:8001' , token: accessToken , // Or provide a token refresh function onTokenExpired : async () => { return await refreshToken (); } });
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 subUnique user identifier for audit logs issOrganization ID derived from realm in the issuer URL groupsMapped to OpenFGA roles for permission checks expToken expiration validation
Error Responses Authentication failures return structured error responses:
Status Code Description 401UNAUTHENTICATEDNo token provided or token signature invalid 401TOKEN_EXPIREDAccess token has expired; refresh and retry 403FORBIDDENToken is valid but user lacks permission for this operation 429RATE_LIMIT_EXCEEDEDToo 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.
