Skip to main content

​
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:
1

Access Workspace Settings

Navigate to your workspace settings in the SundayPyjamas platform.
2

Go to API Tab

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

Generate Key

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

Name Your Key (Optional)

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

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!' }]
  })
});

​
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

​
Security Best Practices

​
✅ Do

  • 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;
  • 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
};
  • 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

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
};
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

1

Navigate to Settings

Go to your workspace settings in the SundayPyjamas web interface.
2

Access API Tab

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

Generate New Key

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

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 env add SUNDAYPYJAMAS_API_KEY

​
Access in Code

const apiKey = process.env.SUNDAYPYJAMAS_API_KEY;

if (!apiKey) {
  throw new Error('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"

​
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