Skip to main content

​
Overview

elizaOS supports multiple authentication methods to secure API access. Authentication ensures that only authorized users and applications can interact with your agents.

​
Authentication Methods

​
API Key Authentication

The primary authentication method uses API keys passed in request headers.

​
Using API Keys

Include your API key in the Authorization header: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/agents

​
Setting API Keys

Configure API keys in your character’s settings: 
{
  "name": "MyAgent",
  "settings": {
    "secrets": {
      "API_KEY": "your-secret-api-key"
    }
  }
}

​
No Authentication (Development)

For local development and testing, you can run elizaOS without authentication: 
# No authentication required for local development
curl http://localhost:3000/agents
Never disable authentication in production environments. Always secure your APIs with proper authentication.

​
Request Headers

​
Required Headers

​
Content-Type
string
required
Set to application/json for all POST, PUT, and PATCH requests

​
Optional Headers

​
Authorization
string
Bearer token for authentication: Bearer YOUR_API_KEY
​
X-Agent-ID
string
Target a specific agent by ID

​
Authentication Examples

​
Node.js

const fetch = require('node-fetch');

const response = await fetch('http://localhost:3000/agents', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

​
Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get('http://localhost:3000/agents', headers=headers)
data = response.json()
print(data)

​
cURL

curl -X GET http://localhost:3000/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Security Best Practices

​
Store Keys Securely

Never hardcode API keys in your source code. Use environment variables: 
export ELIZA_API_KEY="your-api-key"
Then reference them in your code: 
const apiKey = process.env.ELIZA_API_KEY;

​
Rotate Keys Regularly

Change your API keys periodically to minimize security risks:
  1. Generate a new API key
  2. Update your applications to use the new key
  3. Revoke the old key after migration

​
Use HTTPS in Production

Always use HTTPS in production to encrypt API requests: 
https://your-domain.com/agents

​
Implement Rate Limiting

Protect your API from abuse by implementing rate limiting at the reverse proxy or application level.

​
Error Handling

​
401 Unauthorized

Returned when authentication credentials are missing or invalid: 
{
  "success": false,
  "error": "Authentication required"
}

​
403 Forbidden

Returned when authentication succeeds but the user lacks permissions: 
{
  "success": false,
  "error": "Insufficient permissions"
}

​
Next Steps

List Agents

Start making authenticated API requests

Send Message

Send your first message to an agent

Build docs developers (and LLMs) love

Get started for freeTalk to us