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.
JSON Web Tokens (JWTs) are the primary authentication method for web clients and interactive sessions.
Obtain a JWT
JWTs are issued in two scenarios:
access-token
cookie sent to the https://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page/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:
access-token
cookie sent to the https://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page/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 Structure and Signing
JWTs issued by Prisme.ai are signed tokens with the following characteristics:
JWKS_ALG
(default: RS256)JWKS_KTY
(default: RSA)JWKS_SIZE
(default: 2048 bits)The JWT contains claims about the authenticated user, session, and permissions.
Example decoded JWT payload:
JWT Key Rotation
The api-gateway automatically handles JWT key rotation:
JWKS_ROTATION_DAYS
(default: 30 days)ACCESS_TOKENS_MAX_AGE
(default: 30 days) once all their signed JWTs should have expiredgateway.jwks.updated
and runtime.jwks.updated
) synchronize all api-gateway and runtime instances when JWKs are rotated or removedIf 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 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.
x-prismeai-user-id
headerBackend 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.
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.
Learn about common API errors and how to handle them
Understand the API’s rate limiting policies
Read about our security recommendations and best practices
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.
JSON Web Tokens (JWTs) are the primary authentication method for web clients and interactive sessions.
Obtain a JWT
JWTs are issued in two scenarios:
access-token
cookie sent to the https://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page/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:
access-token
cookie sent to the https://api.studio.prisme.ai/v2/me
API after opening any Prisme.ai page/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 Structure and Signing
JWTs issued by Prisme.ai are signed tokens with the following characteristics:
JWKS_ALG
(default: RS256)JWKS_KTY
(default: RSA)JWKS_SIZE
(default: 2048 bits)The JWT contains claims about the authenticated user, session, and permissions.
Example decoded JWT payload:
JWT Key Rotation
The api-gateway automatically handles JWT key rotation:
JWKS_ROTATION_DAYS
(default: 30 days)ACCESS_TOKENS_MAX_AGE
(default: 30 days) once all their signed JWTs should have expiredgateway.jwks.updated
and runtime.jwks.updated
) synchronize all api-gateway and runtime instances when JWKs are rotated or removedIf 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 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.
x-prismeai-user-id
headerBackend 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.
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.
Learn about common API errors and how to handle them
Understand the API’s rate limiting policies
Read about our security recommendations and best practices