Authentication

Spooled uses API keys for authentication. Each key is scoped to an organization and can have specific permissions.

Quick links:

API Keys

API keys authenticate all requests to Spooled. You can create multiple keys with different permissions for different services.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ecfdf5', 'primaryTextColor': '#065f46', 'primaryBorderColor': '#10b981', 'lineColor': '#6b7280'}}}%%
sequenceDiagram
  participant App as Your App
  participant S as Spooled API
  
  App->>S: Request with API Key
  Note right of S: Authorization: Bearer sp_live_...
  S->>S: Validate key
  S-->>App: Response

Key Format

Prefix	Environment	Example
`sp_live_`	Production	`sp_live_abc123def456...`
`sp_test_`	Test/Development	`sp_test_xyz789uvw012...`

Dashboard Tip

Account → API Keys

What to look for:

→ Key name and creation date
→ Last used timestamp
→ Permissions assigned

Actions:

Create new keys
Revoke compromised keys
Rotate keys regularly

Using API Keys

For REST, include your API key or JWT in the Authorization: Bearer … header (JWT tokens are detected by an eyJ prefix). Do not use an X-API-Key header on REST.

Authentication header

# All API requests require authentication
curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue_name": "my-queue", "payload": {...}}'

import { SpooledClient } from '@spooled/sdk';

// Initialize with API key from environment
const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// All subsequent calls are authenticated
const job = await client.jobs.create({...});

from spooled import SpooledClient
import os

# Initialize with API key from environment
client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

# All subsequent calls are authenticated
job = client.jobs.create({...})

# Don't forget to close the client
client.close()

import (
	"os"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
)

// Initialize with API key from environment
client, err := spooled.NewClient(
	spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")),
)
if err != nil {
	panic(err)
}
defer client.Close()

// All subsequent calls are authenticated
job, _ := client.Jobs().Create(ctx, &resources.CreateJobRequest{...})

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

// Initialize with API key from environment
$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// All subsequent calls are authenticated
$job = $client->jobs->create([...]);

For gRPC, pass the API key only in metadata as x-api-key — the gRPC path does not accept JWT.

x-api-key: sp_live_your_api_key

Environment Variables

Never hardcode API keys. Use environment variables to keep them secure.

Environment configuration

# .env file (add to .gitignore!)
SPOOLED_API_KEY=sp_live_your_api_key

# Use in shell
export SPOOLED_API_KEY=sp_live_your_api_key
curl -H "Authorization: Bearer $SPOOLED_API_KEY" ...

// .env file
SPOOLED_API_KEY=sp_live_your_api_key

// Load with dotenv
import 'dotenv/config';
import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

# .env file
SPOOLED_API_KEY=sp_live_your_api_key

# Load with python-dotenv
from dotenv import load_dotenv
from spooled import SpooledClient
import os

load_dotenv()
client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

// .env file (add to .gitignore!)
// SPOOLED_API_KEY=sp_live_your_api_key

import (
	"os"
	"github.com/joho/godotenv"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
)

godotenv.Load() // Load .env file
client, _ := spooled.NewClient(
	spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")),
)

<?php

// .env file (add to .gitignore!)
// SPOOLED_API_KEY=sp_live_your_api_key

// Load with vlucas/phpdotenv
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: $_ENV['SPOOLED_API_KEY'],
));

Security Warning

• Never commit API keys to version control
• Add .env to your .gitignore
• Use different keys for development and production
• Rotate keys periodically

Creating API Keys

Create keys via the dashboard or API:

Create API key

# Create a new API key
curl -X POST https://api.spooled.cloud/api/v1/api-keys \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "permissions": ["jobs:read", "jobs:write", "queues:read"]
  }'

# Response (key shown only once!)
{
  "id": "key_xxxxx",
  "name": "Production Server",
  "key": "sp_live_a1b2c3d4...",
  "permissions": ["jobs:read", "jobs:write", "queues:read"],
  "created_at": "2025-01-15T10:30:00Z"
}

Permissions

API keys can be scoped to specific permissions. Use the principle of least privilege — only grant the permissions each service needs.

Permission	Description	Use Case
`jobs:read`	List and get jobs	Monitoring dashboards
`jobs:write`	Create, complete, fail jobs	Producers and workers
`queues:read`	List queues and stats	Monitoring
`queues:write`	Pause, resume queues	Admin tools
`dlq:read`	List DLQ jobs	Debugging tools
`dlq:write`	Retry, purge DLQ	Admin tools

Key Rotation

Rotate API keys periodically for security. The recommended approach:

Create a new API key with the same permissions
Update your services to use the new key
Verify everything works with the new key
Revoke the old key

API Key Issues

Account → API Keys

What to look for:

→ Key status (active vs revoked)
→ Last used timestamp
→ Key prefix matches environment

Actions:

Check key hasn't been revoked
Verify using correct environment key
Generate a new key if compromised

Rate Limits

API keys are subject to per-plan rate limits. When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header telling you how long to wait before retrying.

The exact request-per-second limits, burst allowances, and quota-enforcement behaviour are listed — as a single source of truth — on the Rate Limits & Quotas page.

Next Steps

Manage your API keys
Quickstart guide — Use your key to create jobs
SDK documentation — Language-specific setup