API Authentication

All Deeployd API requests require authentication. This guide covers how to create, manage, and use API keys.

API Keys

Creating an API Key

From the Dashboard:

1. Go to Settings → API Keys
2. Click + Create API Key
3. Name your key (e.g., "Production", "Development")
4. Select permissions scope
5. Click Create
6. Copy the key immediately - it won't be shown again

# Your API key looks like this
sk_live_abc123...

Using API Keys

Include your API key in the Authorization header:

curl https://api.deeployd.com/v1/agents \
  -H "Authorization: Bearer sk_live_abc123..."

Or with the SDK:

import { DeepLoyd } from '@deeployd/sdk';

const client = new DeepLoyd({
  apiKey: 'sk_live_abc123...'
});

Key Types

Type	Prefix	Purpose
Live	sk_live_	Production use
Test	sk_test_	Development/testing

Test Keys

Test keys access the sandbox environment:

• No charges incurred
• Data not persisted long-term
• Rate limits relaxed
• Safe for development

const client = new DeepLoyd({
  apiKey: 'sk_test_abc123...',
  testMode: true
});

Permissions

API keys can be scoped to specific permissions:

Permission	Description
agents:read	List and get agents
agents:write	Create, update, delete agents
conversations:read	List and get conversations
conversations:write	Create conversations, send messages
tasks:read	List and get tasks
tasks:write	Create, update, run tasks
workflows:read	List and get workflows
workflows:write	Create, update, run workflows
memory:read	Read memory values
memory:write	Set and delete memory
admin	Full administrative access

Example: Read-Only Key

# Create via API
curl -X POST https://api.deeployd.com/v1/api-keys \
  -H "Authorization: Bearer sk_live_admin..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Dashboard",
    "permissions": ["agents:read", "conversations:read", "tasks:read"]
  }'

Key Management

List API Keys

const keys = await client.apiKeys.list();

for (const key of keys.data) {
  console.log({
    id: key.id,
    name: key.name,
    prefix: key.prefix,
    createdAt: key.createdAt,
    lastUsedAt: key.lastUsedAt
  });
}

Revoke API Key

await client.apiKeys.revoke('key-123');

Rotate API Key

const newKey = await client.apiKeys.rotate('key-123');
console.log(newKey.apiKey); // New key value

Security Best Practices

1. Never Expose Keys in Code

// ❌ Bad - hardcoded key
const client = new DeepLoyd({
  apiKey: 'sk_live_abc123...'
});

// ✅ Good - environment variable
const client = new DeepLoyd({
  apiKey: process.env.DEEPLOYD_API_KEY
});

2. Use Minimal Permissions

// ✅ Good - only the permissions needed
permissions: ['agents:read', 'conversations:write']

// ❌ Bad - overly broad
permissions: ['admin']

3. Rotate Keys Regularly

Set up periodic key rotation, especially for production keys.

4. Monitor Key Usage

Check the Dashboard for:

• Last used timestamp
• Request counts
• Error rates

5. Use Different Keys Per Environment

# Development
DEEPLOYD_API_KEY=sk_test_dev...

# Staging
DEEPLOYD_API_KEY=sk_test_staging...

# Production
DEEPLOYD_API_KEY=sk_live_prod...

OAuth 2.0 (Enterprise)

Enterprise customers can use OAuth 2.0 for machine-to-machine authentication.

Client Credentials Flow

const tokenResponse = await fetch('https://auth.deeployd.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    scope: 'agents:read conversations:write'
  })
});

const { access_token } = await tokenResponse.json();

// Use the token
const client = new DeepLoyd({
  accessToken: access_token
});

Token Refresh

Access tokens expire after 1 hour. Implement token refresh:

async function getValidToken() {
  if (isTokenExpired(currentToken)) {
    currentToken = await refreshToken();
  }
  return currentToken;
}

Rate Limiting

API keys are subject to rate limits:

Plan	Requests/min	Burst
Starter	60	100
Pro	300	500
Business	1000	2000
Enterprise	Custom	Custom

Rate limit headers in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705312200

Error Responses

401 Unauthorized

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid API key"
  }
}

Common causes:

• Missing API key
• Invalid or revoked key
• Expired token (OAuth)

403 Forbidden

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Insufficient permissions for this operation"
  }
}

Common causes:

• Key lacks required permission
• Accessing another tenant's resources

---

Next: Learn about Webhooks for receiving real-time events.