Authentication API
The Authentication API manages API keys for accessing Dispersl services. All API endpoints require Bearer token authentication unless otherwise noted.
Overview
Dispersl uses API key-based authentication with Bearer tokens. Each API key provides access to:
- Agent endpoints for AI operations
- Task and step management
- Analytics and monitoring
- Model selection and usage
Endpoints
Get API Keys
GET /keys
Retrieves all API keys for the authenticated user.
Headers
Authorization: Bearer YOUR_API_KEYResponse
{
"apiKeys": [
{
"name": "Production API Key",
"publicKey": "pk_live_1234567890abcdef",
"created_at": "2024-01-15T10:30:00Z"
},
{
"name": "Development API Key",
"publicKey": "pk_test_abcdef1234567890",
"created_at": "2024-01-10T14:20:00Z"
}
]
}Generate New API Key
GET /keys/new
Generates a new API key pair for the user.
Response
{
"publicKey": "pk_live_new1234567890abcdef",
"message": "API key generated successfully"
}Authentication Methods
Bearer Token
Include your API key in the Authorization header:
curl -H "Authorization: Bearer pk_live_1234567890abcdef" \
https://api.dispersl.com/v1/agent/chatJavaScript/Node.js
const response = await fetch('https://api.dispersl.com/v1/agent/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_1234567890abcdef',
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt: 'Hello, Dispersl!',
model: 'anthropic/claude-3-sonnet'
})
});Python
import requests
headers = {
'Authorization': 'Bearer pk_live_1234567890abcdef',
'Content-Type': 'application/json'
}
response = requests.post(
'https://api.dispersl.com/v1/agent/chat',
headers=headers,
json={
'prompt': 'Hello, Dispersl!',
'model': 'anthropic/claude-3-sonnet'
}
)API Key Types
Live Keys (pk_live_)
- Used for production environments
- Full access to all features
- Rate limits apply based on your plan
- Charges apply for usage
Test Keys (pk_test_)
- Used for development and testing
- Limited to test mode features
- Lower rate limits
- No charges for usage
Security Best Practices
Key Management
- Keep keys secure: Never expose API keys in client-side code
- Use environment variables: Store keys in environment variables
- Rotate regularly: Generate new keys periodically
- Limit scope: Use test keys for development
Environment Variables
# .env file
DISPERSL_API_KEY=pk_live_1234567890abcdef
DISPERSL_BASE_URL=https://api.dispersl.com/v1Key Rotation
// Example key rotation workflow
const oldKey = process.env.DISPERSL_API_KEY;
const newKey = await generateNewApiKey();
// Update environment
process.env.DISPERSL_API_KEY = newKey;
// Verify new key works
await testApiKey(newKey);
// Revoke old key if needed
await revokeApiKey(oldKey);Rate Limits
Rate limits are enforced per API key:
| Plan | Requests per Hour | Concurrent Requests |
|---|---|---|
| Free | 100 | 2 |
| Pro | 1,000 | 10 |
| Enterprise | Custom | Custom |
Rate Limit Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200Error Responses
401 Unauthorized
{
"error": {
"code": 401,
"message": "No Bearer token provided"
}
}400 Bad Request
{
"error": {
"code": 400,
"message": "Failed to verify api_key or token"
}
}429 Too Many Requests
{
"error": {
"code": 429,
"message": "Rate limit exceeded"
}
}MCP Server Integration
Dispersl can also run as an MCP (Model Context Protocol) server. Configure your MCP client:
Cursor Configuration
Add to .cursor/mcp.json:
{
"mcpServers": {
"dispersl": {
"url": "https://dispersl.com/ot/pk_live_dad3qaef..."
}
}
}Windsurf Configuration
{
"mcp": {
"servers": {
"dispersl": {
"command": "npx",
"args": ["dispersl-mcp"],
"env": {
"DISPERSL_API_KEY": "pk_live_1234567890abcdef"
}
}
}
}
}Getting Started
- Sign up for a Dispersl account
- Generate your first API key using the
/keys/newendpoint - Test the connection with a simple chat request
- Integrate into your development workflow
Support
- Documentation: Check our comprehensive API docs
- Community: Join our Discord for community support
- Enterprise: Contact us for enterprise authentication solutions