Getting Started

Authentication

Secure your API requests with API key authentication, scoping, and rate limiting.

API Key Authentication

All requests to the Agent Dojo API require authentication using the X-API-Key header. API keys are scoped to a specific API and optionally to a project, ensuring fine-grained access control.

curl -H "X-API-Key: your-api-key" \
  https://api.agentdojo.dev/mcp/servers

Key Scoping

API keys are scoped to control what resources they can access. Each key has the following scope attributes:

Scope	Required	Description
`api_id`	Yes	The key only works for one specific API. Every key is bound to a single API.
`project_id`	No	Optional project scope. When `null`, the key can access all projects. When set, the key can only access that specific project's resources.

Rate Limiting

API endpoints are rate-limited to ensure fair usage. Limits are applied per API key.

Endpoint	Rate Limit
List servers	60 requests / minute
Create server	20 requests / minute
Call tools	1,000 requests / minute
Protocol (initialize, etc.)	100 requests / minute

Error Responses

When authentication fails, the API returns a 401 Unauthorized status code. This occurs when the API key is missing, invalid, or expired.

{
  "success": false,
  "error": "Invalid or expired API key",
  "code": "UNAUTHORIZED"
}

Common causes of authentication errors:

Missing X-API-Key header in the request
API key has been revoked or has expired
API key does not have access to the requested resource (wrong api_id or project_id scope)

Security Best Practices

Never expose keys in client-side code

API keys should only be used in server-side code or secure backend environments. Never include them in frontend JavaScript, mobile apps, or any code that runs in the browser.

Use environment variables

Store API keys in environment variables rather than hardcoding them in your source code. This prevents accidental exposure through version control.

export AGENT_DOJO_API_KEY="your-api-key"

# Use in your application
const apiKey = process.env.AGENT_DOJO_API_KEY;

Rotate keys regularly

Periodically generate new API keys and revoke old ones. This limits the impact of any compromised key and maintains a strong security posture.