Authentication

Learn how to authenticate your API requests with ServoAgent.

API Key Authentication

ServoAgent uses API keys to authenticate requests. You can create and manage API keys in your dashboard.

Include your API key in the request header:

curl https://api.servoagent.com/v1/agents \
  -H "Authorization: Bearer sk_your_api_key"

Alternatively, you can use the X-API-Key header:

curl https://api.servoagent.com/v1/agents \
  -H "X-API-Key: sk_your_api_key"

API Key Types

Production Keys

Prefix: sk_live_

Use for production environments. Has full access based on assigned scopes.

Test Keys

Prefix: sk_test_

Use for development and testing. Operates in sandbox mode.

API Scopes

API keys can be created with specific scopes to limit access:

Scope	Description
`agents:read`	Read agent information
`agents:write`	Create, update, and delete agents
`agents:execute`	Execute agents and create runs
`contacts:read`	Read contact information
`contacts:write`	Create, update, and delete contacts
`analytics:read`	Read analytics and metrics
`webhooks:manage`	Create and manage webhooks
`billing:read`	Read billing information
`workspace:admin`	Full workspace administration

Security Best Practices

Never expose your API key in client-side code or public repositories
Use environment variables to store API keys
Create keys with the minimum required scopes
Rotate keys regularly, especially after team member changes
Set IP allowlists for production keys
Use separate keys for development and production

SDK Authentication

import os
from servoagent import ServoAgentClient

# From environment variable (recommended)
client = ServoAgentClient(
    api_key=os.environ.get("SERVOAGENT_API_KEY")
)

# Or directly (not recommended for production)
client = ServoAgentClient(
    api_key="sk_live_your_api_key"
)

Authentication Errors

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have required scope: agents:execute"
  }
}