Authentication
Learn how to authenticate with the Prisme.ai API
The Prisme.ai API uses a robust authentication system to secure access to resources. This guide explains how authentication works and how to implement it in your API requests.
Authentication Methods
JSON Web Tokens (JWTs) are the primary authentication method for web clients and interactive sessions.
Obtain a JWT
JWTs are issued in two scenarios:
- OpenID Connect (OIDC) authentication: After authenticating with the OIDC server (the api-gateway), clients receive an authorization code that can be exchanged for a JWT. Find your current JWT in the
access-token
cookie sent to thehttps://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page - Anonymous authentication: The
/v2/login/anonymous
endpoint initiates unauthenticated sessions and returns a JWT.
Response contains a JWT:
Use the JWT
Include the JWT in the Authorization header for API requests:
JWTs have an expiration time defined by the ACCESS_TOKENS_MAX_AGE
setting (default is 30 days). Your application should handle token refreshing or re-authentication when tokens expire.
JSON Web Tokens (JWTs) are the primary authentication method for web clients and interactive sessions.
Obtain a JWT
JWTs are issued in two scenarios:
- OpenID Connect (OIDC) authentication: After authenticating with the OIDC server (the api-gateway), clients receive an authorization code that can be exchanged for a JWT. Find your current JWT in the
access-token
cookie sent to thehttps://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page - Anonymous authentication: The
/v2/login/anonymous
endpoint initiates unauthenticated sessions and returns a JWT.
Response contains a JWT:
Use the JWT
Include the JWT in the Authorization header for API requests:
JWTs have an expiration time defined by the ACCESS_TOKENS_MAX_AGE
setting (default is 30 days). Your application should handle token refreshing or re-authentication when tokens expire.
Access tokens are opaque tokens generated for longer-term programmatic access. They are ideal for scripts, integrations, and backend applications.
Generate an Access Token
Authenticated users can generate access tokens using the /v2/user/accessTokens
endpoint:
The response includes the access token:
Use the Access Token
Include the access token in the Authorization header the same way as JWTs:
Access tokens cannot be recovered if lost. Store them securely and never expose them in client-side code.
API keys are scoped to specific workspaces and provide granular permission control for integrations.
Create an API Key
Workspace administrators can create API keys with specific permissions:
The response includes the API key:
Use the API Key
Include the API key in the x-prismeai-api-key header:
API keys follow the principle of least privilege. They only have the permissions explicitly granted during creation.
JWT Token Details
JWT Structure and Signing
JWT Structure and Signing
JWTs issued by Prisme.ai are signed tokens with the following characteristics:
- Algorithm: Defined by
JWKS_ALG
(default: RS256) - Key Type: Defined by
JWKS_KTY
(default: RSA) - Key Size: Defined by
JWKS_SIZE
(default: 2048 bits)
The JWT contains claims about the authenticated user, session, and permissions.
Example decoded JWT payload:
JWT Key Rotation
JWT Key Rotation
The api-gateway automatically handles JWT key rotation:
- JWTs are signed using a JSON Web Key (JWK) that is stored in the api-gateway database
- JWKs are automatically rotated according to
JWKS_ROTATION_DAYS
(default: 30 days) - When a JWK is rotated, it remains available for verification of existing JWTs
- Rotated JWKs are removed after
ACCESS_TOKENS_MAX_AGE
(default: 30 days) once all their signed JWTs should have expired - Events (
gateway.jwks.updated
andruntime.jwks.updated
) synchronize all api-gateway and runtime instances when JWKs are rotated or removed
If a signing JWK is compromised, it must be manually deleted from the database before restarting both api-gateway and runtime services.
Public Keys
Public Keys
Public keys for verifying JWTs are available at:
This endpoint returns the public keys in JWKS (JSON Web Key Set) format, which can be used to verify token signatures.
Authentication Flow
- Client Authentication: The client authenticates via OIDC or anonymous login to obtain a JWT
- API Gateway Validation: Requests are sent to the api-gateway with the JWT or access token
- Header Transformation: The api-gateway validates the token and adds an
x-prismeai-user-id
header - Internal Routing: The request is forwarded to the appropriate microservice with the user context
- Authorization Check: The target microservice checks if the authenticated user has the required permissions
Backend microservices rely on the x-prismeai-user-id
header for identification. This header should not be directly set in client requests, as it will be overwritten by the api-gateway.
Token Security
Token Storage
- Store tokens securely (not in localStorage for browser applications)
- Use HttpOnly cookies where possible
- For mobile apps, use secure storage mechanisms
- For server applications, use environment variables or secure vaults
Token Transmission
- Always use HTTPS/TLS for API communication
- Use Authorization header rather than query parameters
- Don’t include tokens in URLs or log them
- Implement CSRF protection for cookie-based authentication
Token Management
- Implement token refresh strategies
- Set appropriate token expiration times
- Have processes for token revocation
- Regularly rotate long-lived tokens
Error Handling
- Handle 401 (Unauthorized) responses properly
- Don’t expose detailed error information to clients
- Implement rate limiting for authentication failures
- Log authentication failures for security monitoring
Authentication Configuration
JWT and authentication behavior can be configured with these environment variables:
Variable | Description | Default Value |
---|---|---|
JWKS_ROTATION_DAYS | Rotation period in days | 30 |
JWKS_KTY | JWK Algorithm family | RSA |
JWKS_ALG | JWK signature algorithm | RS256 |
JWKS_SIZE | JWK size | 2048 |
ACCESS_TOKENS_MAX_AGE | JWT expiration time in seconds | 2592000 (30 days) |
JWT and authentication behavior can be configured with these environment variables:
Variable | Description | Default Value |
---|---|---|
JWKS_ROTATION_DAYS | Rotation period in days | 30 |
JWKS_KTY | JWK Algorithm family | RSA |
JWKS_ALG | JWK signature algorithm | RS256 |
JWKS_SIZE | JWK size | 2048 |
ACCESS_TOKENS_MAX_AGE | JWT expiration time in seconds | 2592000 (30 days) |
Each workspace manages its own permissions system using Role Based Access Control (RBAC).
See the Security page for more details on the authorization system.