Skip to main content

​
Authentication

Crew supports multiple authentication methods depending on your use case. This guide covers API keys for server-to-server communication and JWT tokens for user-scoped access.

​
Authentication Methods

MethodUse Case
API KeysServer-to-server, backend integrations
JWT TokensUser-scoped access, frontend applications
OAuth 2.0Third-party integrations (Enterprise)

​
API Keys

API keys provide full access to your workspace’s resources. Use them for backend integrations and server-to-server communication.

​
Creating API Keys

1

Navigate to Settings

Go to your Workspace → Settings → API Keys
2

Create New Key

Click Create API Key
3

Name and Configure

Give it a descriptive name and set permissions
4

Copy Key

Copy the key immediately—it won’t be shown again

​
Using API Keys

Include the key in the Authorization header: 
curl https://api.usecrew.ai/v1/agents \
  -H "Authorization: Bearer crew_sk_live_xxxxxxxxxxxx"

​
Key Prefixes

PrefixEnvironment
crew_sk_live_Production
crew_sk_test_Sandbox/Test
Never expose API keys in frontend code, public repositories, or client-side applications.

​
Key Permissions

Scope API keys to specific permissions: 
{
  "name": "Call Analytics Key",
  "permissions": [
    "calls:read",
    "agents:read",
    "analytics:read"
  ]
}
PermissionDescription
*:readRead access to all resources
*:writeWrite access to all resources
calls:readRead call data
calls:writeCreate and modify calls
agents:readRead agent configurations
agents:writeModify agent configurations
analytics:readAccess analytics data

​
Rotating Keys

Rotate keys periodically for security:
1

Create New Key

Create a new API key with the same permissions
2

Update Applications

Update your applications to use the new key
3

Revoke Old Key

Delete the old key once all applications are updated

​
Revoking Keys

Immediately revoke compromised keys: 
curl -X DELETE https://api.usecrew.ai/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
JWT Tokens

JWT tokens provide user-scoped access, ideal for frontend applications and user-specific operations.

​
Generating Tokens

Generate tokens server-side: 
curl -X POST https://api.usecrew.ai/v1/auth/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_12345",
    "permissions": ["calls:read", "agents:read"],
    "expires_in": 3600
  }'
Response: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-15T11:30:00Z"
}

​
Using JWT Tokens

curl https://api.usecrew.ai/v1/calls \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

​
Token Structure

{
  "sub": "user_12345",
  "iss": "https://api.usecrew.ai",
  "aud": "crew_api",
  "iat": 1705312800,
  "exp": 1705316400,
  "permissions": ["calls:read", "agents:read"],
  "workspace_id": "ws_xyz789"
}

​
Refreshing Tokens

Before expiration, refresh tokens: 
curl -X POST https://api.usecrew.ai/v1/auth/refresh \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
OAuth 2.0 (Enterprise)

For third-party integrations, Crew supports OAuth 2.0.

​
Authorization Code Flow

  1. Redirect to authorization:
https://api.usecrew.ai/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=calls:read agents:read
  1. User authorizes the application
  2. Exchange code for token: 
curl -X POST https://api.usecrew.ai/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

​
Client Credentials Flow

For server-to-server without user context: 
curl -X POST https://api.usecrew.ai/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=calls:read agents:read"

​
Security Best Practices

​
API Keys

Use environment variables or secret managers. Never hardcode keys.
Grant only the permissions needed for each key.
Rotate keys at least every 90 days.
Review API key usage logs for anomalies.
Development, staging, and production should have different keys.

​
JWT Tokens

Use short-lived tokens (1 hour or less).
Always validate tokens server-side before trusting claims.
Never transmit tokens over unencrypted connections.

​
IP Allowlisting

Restrict API access to specific IP addresses: 
curl -X PUT https://api.usecrew.ai/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "allowed_ips": [
      "203.0.113.10",
      "203.0.113.0/24"
    ]
  }'

​
Audit Logging

All authentication events are logged:
EventDescription
api_key.createdNew API key created
api_key.usedAPI key used for request
api_key.revokedAPI key deleted
token.issuedJWT token generated
token.refreshedJWT token refreshed
auth.failedAuthentication failure
Access logs via API: 
curl https://api.usecrew.ai/v1/audit-logs?type=auth \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Error Codes

CodeDescriptionSolution
invalid_api_keyKey is malformedCheck key format
expired_api_keyKey has been revokedCreate new key
insufficient_permissionsKey lacks required permissionAdd permissions
expired_tokenJWT has expiredRefresh token
invalid_tokenJWT signature invalidGenerate new token
ip_not_allowedRequest from blocked IPUpdate allowlist

​
Next Steps

  • API Overview — Full API reference
  • Webhooks — Secure webhook verification
  • SSO — Enterprise identity management