Authentication - SundayPyjamas AI Suite

Overview

The SundayPyjamas AI Suite API uses API keys for authentication. All API requests must include a valid API key in the Authorization header.

API keys provide secure access to the API while maintaining workspace-level isolation and usage tracking.

API Key Format

API keys follow this specific format:

spj_ai_[64-character-random-string]

Example:

spj_ai_a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234

API keys are only shown once during creation. Store them securely immediately after generation!

Getting Your API Key

Follow these steps to generate your API key:

Access Workspace Settings

Navigate to your workspace settings in the SundayPyjamas platform.

Go to API Tab

Click on the “API” tab in your workspace settings.

Generate Key

Click “Generate API Key” to create a new key.

Name Your Key (Optional)

Give your API key a descriptive name to help you identify it later.

Copy and Store

Copy the generated key immediately and store it securely. It won’t be shown again!

Making Authenticated Requests

Include your API key in the Authorization header with the Bearer scheme:

const response = await fetch('https://suite.sundaypyjamas.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer spj_ai_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

import requests

response = requests.post(
    'https://suite.sundaypyjamas.com/api/v1/chat',
    headers={
        'Authorization': 'Bearer spj_ai_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [{'role': 'user', 'content': 'Hello!'}]
    }
)

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

Permissions and Access Control

API keys inherit the permissions of the user who created them:

Workspace Access

Keys can only access the workspace they were created in

Role Requirements

Only workspace owners and admins can create/manage API keys

Token Limits

API usage counts toward your workspace token limit

Usage Tracking

Monitor API key usage through workspace analytics

Auth by API Group

Most endpoints accept your workspace API key exactly as described above. A few groups differ:

API	Accepts API key?	Notes
Chat, Agents, Artifacts, Image, Vector Store, Apps, Insights	✅	Standard `Bearer spj_ai_...`
Apps, Vector Store	✅ (+ widget token)	Also accept a workspace/app-scoped widget token as a fallback, for calls made directly from an embedded browser widget
RAG	❌ (currently)	Requires a Supabase session token — the same auth as the AI Suite web app. Not yet available via workspace API key
Integration Packs list, Platform Tools	Public	No authentication required — these are read-only catalog endpoints
MCP Connectors connect/disconnect/toggle	❌	Session only, and restricted to workspace `owner`/`admin` — not available via API key
Storage	✅ (+ session)	Accepts either an API key or a session, whichever you have

Security Best Practices

✅ Do

Store API keys securely

Use environment variables or secure key management systems
Never hardcode API keys in your source code
Use different API keys for different applications/environments

# .env file
SUNDAYPYJAMAS_API_KEY=spj_ai_your_api_key_here

// In your application
const apiKey = process.env.SUNDAYPYJAMAS_API_KEY;

Rotate API keys regularly

Generate new API keys periodically
Deactivate old keys after replacement
Use descriptive names to track key usage

// Example rotation strategy
const config = {
  apiKey: process.env.SUNDAYPYJAMAS_API_KEY,
  // Fallback key for seamless rotation
  fallbackApiKey: process.env.SUNDAYPYJAMAS_FALLBACK_API_KEY
};

Monitor API key usage

Review usage analytics regularly
Set up alerts for unusual activity
Track token consumption patterns

Use workspace analytics to monitor which API keys are consuming the most tokens and identify optimization opportunities.

❌ Don’t

Never expose API keys in client-side code

API keys should never be included in frontend JavaScript, mobile apps, or any client-side code where users can access them.

// ❌ Never do this - API key exposed to users
const apiKey = 'spj_ai_your_api_key_here';
fetch('/api/chat', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

// ✅ Use a backend proxy instead
fetch('/api/chat-proxy', {
  headers: { 'Authorization': `Bearer ${userSessionToken}` }
});

Use separate API keys for different applications to maintain better security and usage tracking.

// ❌ Shared key across projects
const sharedApiKey = 'spj_ai_shared_key';

// ✅ Separate keys per application
const config = {
  webApp: process.env.WEBAPP_API_KEY,
  mobileApp: process.env.MOBILE_API_KEY,
  analytics: process.env.ANALYTICS_API_KEY
};

Never commit API keys to version control

Use .gitignore to exclude files containing API keys and use environment variables instead.

# .gitignore
.env
.env.local
.env.production
config/secrets.json

API Key Management

Creating API Keys

Navigate to Settings

Go to your workspace settings in the SundayPyjamas web interface.

Access API Tab

Click on the “API” tab to view key management options.

Generate New Key

Click “Generate API Key” and optionally provide a descriptive name.

Save Securely

Copy the generated key immediately and store it in your secure key management system.

Managing Existing Keys

In your workspace API settings, you can:

View all active API keys with their names and creation dates
Delete keys you no longer need
Monitor usage for each individual key
Track token consumption per API key

API key creation and management is done exclusively through the web interface to ensure proper security and access control.

Rate Limits and Quotas

Per Workspace Limit

Maximum 10 active API keys per workspace

Token-based Usage

API usage counts toward workspace token quotas

Request Rate Limits

Standard rate limiting applies to all API endpoints

Fair Usage Policy

Usage monitoring to ensure fair access for all users

Error Responses

Invalid API Key (401)

{
  "error": "Invalid API key"
}

Common causes:

API key doesn’t exist or has been deleted
Incorrect API key format
Missing or malformed Authorization header

Solution:

Verify your API key is correct and active
Check the Authorization header format: Bearer spj_ai_...
Generate a new API key if necessary

Insufficient Permissions (403)

{
  "error": "Insufficient permissions to create API keys"
}

Cause: User doesn’t have required role (owner/admin) for API key management Solution: Contact your workspace owner to grant appropriate permissions

Token Limit Exceeded (403)

{
  "error": "Token limit exceeded"
}

Solutions:

Wait for your monthly token reset
Upgrade your subscription plan
Optimize prompts to reduce token usage

Environment Variables Best Practices

Local Development

Create a .env file for local development:

# .env
SUNDAYPYJAMAS_API_KEY=spj_ai_your_development_key_here
SUNDAYPYJAMAS_API_URL=https://suite.sundaypyjamas.com/api/v1

Production Deployment

Set environment variables in your deployment platform:

Vercel
Netlify
Heroku
AWS Lambda

vercel env add SUNDAYPYJAMAS_API_KEY

netlify env:set SUNDAYPYJAMAS_API_KEY spj_ai_your_key_here

heroku config:set SUNDAYPYJAMAS_API_KEY=spj_ai_your_key_here

aws lambda update-function-configuration \
  --function-name your-function \
  --environment Variables='{SUNDAYPYJAMAS_API_KEY=spj_ai_your_key_here}'

Access in Code

const apiKey = process.env.SUNDAYPYJAMAS_API_KEY;

if (!apiKey) {
  throw new Error('SUNDAYPYJAMAS_API_KEY environment variable is required');
}

import os

api_key = os.getenv('SUNDAYPYJAMAS_API_KEY')

if not api_key:
    raise ValueError("SUNDAYPYJAMAS_API_KEY environment variable is required")

package main

import (
    "os"
    "log"
)

func main() {
    apiKey := os.Getenv("SUNDAYPYJAMAS_API_KEY")
    if apiKey == "" {
        log.Fatal("SUNDAYPYJAMAS_API_KEY environment variable is required")
    }
}

Testing Authentication

Verify API Key

Test your API key with a simple request:

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer ${SUNDAYPYJAMAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Test"}]}' \
  -w "\nHTTP Status: %{http_code}\n"

async function testApiKey() {
  try {
    const response = await fetch('https://suite.sundaypyjamas.com/api/v1/chat', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SUNDAYPYJAMAS_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messages: [{ role: 'user', content: 'Test' }]
      })
    });

    if (response.ok) {
      console.log('✅ API key is valid');
    } else {
      console.log('❌ API key is invalid');
    }
  } catch (error) {
    console.error('Connection error:', error);
  }
}

import requests

def test_api_key():
    try:
        response = requests.post(
            'https://suite.sundaypyjamas.com/api/v1/chat',
            headers={
                'Authorization': f'Bearer {os.getenv("SUNDAYPYJAMAS_API_KEY")}',
                'Content-Type': 'application/json'
            },
            json={'messages': [{'role': 'user', 'content': 'Test'}]}
        )
        
        if response.ok:
            print('✅ API key is valid')
        else:
            print('❌ API key is invalid')
            
    except requests.exceptions.RequestException as e:
        print(f'Connection error: {e}')

Next Steps

Chat API

Start making requests to the Chat API with your authenticated key

Rate Limits

Understand usage limits and optimization strategies

Code Examples

View complete implementation examples with authentication

Error Handling

Learn how to handle authentication errors gracefully

​Overview

​API Key Format

​Getting Your API Key

​Making Authenticated Requests

​Permissions and Access Control

Workspace Access

Role Requirements

Token Limits

Usage Tracking

​Auth by API Group

​Security Best Practices

​✅ Do

​❌ Don’t

​API Key Management

​Creating API Keys

​Managing Existing Keys

​Rate Limits and Quotas

Per Workspace Limit

Token-based Usage

Request Rate Limits

Fair Usage Policy

​Error Responses

​Invalid API Key (401)

​Insufficient Permissions (403)

​Token Limit Exceeded (403)

​Environment Variables Best Practices

​Local Development

​Production Deployment

​Access in Code

​Testing Authentication

​Verify API Key

​Next Steps

Chat API

Rate Limits

Code Examples

Error Handling

Overview

API Key Format

Getting Your API Key

Making Authenticated Requests

Permissions and Access Control

Auth by API Group

Security Best Practices

✅ Do

❌ Don’t

API Key Management

Creating API Keys

Managing Existing Keys

Rate Limits and Quotas

Error Responses

Invalid API Key (401)

Insufficient Permissions (403)

Token Limit Exceeded (403)

Environment Variables Best Practices

Local Development

Production Deployment

Access in Code

Testing Authentication

Verify API Key

Next Steps