Authentication

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

JWT Authentication
Access Tokens
API Keys

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 the https://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.

# Example of anonymous login
curl -X POST "https://api.studio.prisme.ai/v2/login/anonymous" \
     -H "Content-Type: application/json"

Response contains a JWT:

{
  "userId": "anon-123456",
  "sessionId": "session-789012",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0xIn0..."
}

Use the JWT

Include the JWT in the Authorization header for API requests:

curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0xIn0..."

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:

curl -X POST "https://api.studio.prisme.ai/v2/user/accessTokens" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_JWT" \
     -d '{
           "name": "My Integration Token",
           "expiresAt": "2025-04-28T10:13:21.719Z"
         }'

The response includes the access token:

{
  "name": "My Integration Token",
  "expiresAt": "2023-12-31T23:59:59Z",
  "userId": "user id",
  "token": "at:1234abcd5678efgh",
  "_id": "token id"
}

Use the Access Token

Include the access token in the Authorization header the same way as JWTs:

curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer at:1234abcd5678efgh"

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:

  curl --location 'https://api.studio.prisme.ai/v2/workspaces/<WORKSPACE_ID>/security/apikeys' \
  --header 'Authorization: Bearer <YOUR_JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
      "name": "Your ApiKey name",
      "rules": [
          {
              "action": "read",
              "subject": "workspaces"
          },                
          {
              "action": "create",
              "subject": "files"
          }
      ]
  }'

The response includes the API key:

  {
      "apiKey": "<apikey>",
      "name": "Your ApiKey name",
      "rules": [
          {
              "action": [
                  "read"
              ],
              "subject": "workspaces",
              "conditions": {
                  "id": "<WORKSPACE_ID>"
              }
          },                
          {
              "action": [
                  "create"
              ],
              "subject": "files",
              "conditions": {
                  "workspaceId": "<WORKSPACE_ID>"
              }
          }
      ],
      "subjectId": "<WORKSPACE_ID>",
      "subjectType": "workspaces"
  }

See RBAC for more advanced rules

Use the API Key

Include the API key in the x-prismeai-api-key header:

curl -X GET "https://api.studio.prisme.ai/v2/workspaces/{workspaceId}" \
     -H "Content-Type: application/json" \
     -H "x-prismeai-api-key: <apikey>"

API keys follow the principle of least privilege. They only have the permissions explicitly granted during creation.

JWT Token Details

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:

  {
    "prismeaiSessionId": "session id",
    "jti": "...",
    "sub": "user id",
    "iat": 1744705420,
    "exp": 1747297420,
    "scope": "events:write events:read webhooks pages:read files:write files:read",
    "client_id": "prismeai-studio-client",
    "iss": "...",
    "aud": "..."
  }

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 and runtime.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 for verifying JWTs are available at:

https://api.studio.prisme.ai/oidc/jwks

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

Environment Variables
Authorization 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)

Code Examples

Node.js
Python
cURL

const axios = require('axios');

async function getPrismeData() {
  // Get or refresh your token using your authentication method
  const token = 'YOUR_ACCESS_TOKEN';
  
  try {
    const response = await axios.get('https://api.studio.prisme.ai/v2/workspaces', {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    return response.data;
  } catch (error) {
    if (error.response && error.response.status === 401) {
      // Handle authentication error, potentially refresh token
      console.error('Authentication failed, token may be expired');
    } else {
      console.error('API request failed:', error.message);
    }
    throw error;
  }
}

import requests

def get_prisme_data():
    # Get or refresh your token using your authentication method
    token = 'YOUR_ACCESS_TOKEN'
    
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    
    try:
        response = requests.get('https://api.studio.prisme.ai/v2/workspaces', headers=headers)
        response.raise_for_status()  # Raise exception for HTTP errors
        return response.json()
    except requests.exceptions.HTTPError as err:
        if err.response.status_code == 401:
            # Handle authentication error, potentially refresh token
            print('Authentication failed, token may be expired')
        else:
            print(f'API request failed: {err}')
        raise

# Set your token as a variable
TOKEN="YOUR_ACCESS_TOKEN"

# Make API request
curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN"

Next Steps

Error Handling

Learn about common API errors and how to handle them

Rate Limits

Understand the API’s rate limiting policies

Security

Read about our security recommendations and best practices

Introduction

AI Builder Endpoints

Authentication Methods

JWT Token Details

Authentication Flow

Token Security

Token Storage

Token Transmission

Token Management

Error Handling

Authentication Configuration

Code Examples

Next Steps

Error Handling

Rate Limits

Security

Introduction

AI Builder Endpoints

​Authentication Methods

​JWT Token Details

​Authentication Flow

​Token Security

Token Storage

Token Transmission

Token Management

Error Handling

​Authentication Configuration

​Code Examples

​Next Steps

Error Handling

Rate Limits

Security

Authentication Methods

JWT Token Details

Authentication Flow

Token Security

Authentication Configuration

Code Examples

Next Steps