Authentication

Base URL and Authentication

Base URL: http://localhost:5757/api/v1 (or your deployment URL)

Authentication Methods:

• Cookie Authentication: For web sessions (login required)
• API Keys: For programmatic access (see API Key Management section)
• Agent Keys: For agent-specific operations

🔐 User Authentication

User Registration

POST /api/v1/auth/register
Content-Type: application/x-www-form-urlencoded

[email protected]&password=yourpassword&confirm_password=yourpassword&first_name=John&last_name=Doe

Response: Redirects to login page on success

User Login

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

[email protected]&password=yourpassword

Response: Sets authentication cookie and redirects to main app

Logout

POST /api/v1/auth/logout

Response: Clears authentication cookie and redirects to login

🔑 API Key Management

Essential for programmatic access to the platform.

Create API Key

POST /api/v1/user/api-keys
Authorization: Bearer <session_token>
Content-Type: application/json

{
    "name": "My Integration Key",
    "scopes": ["read:all", "write:all"]
}

Available Scopes:

• read:all - Read access to all resources
• write:all - Write access to all resources
• admin - Administrative access
• app:access - Application-specific access

Response:

{
    "id": 1,
    "name": "My Integration Key",
    "key": "fw_key_abc123...",
    "key_prefix": "fw_key_abc1",
    "scopes": ["read:all", "write:all"],
    "expires_at": null,
    "created_at": "2024-01-01T00:00:00Z"
}

List API Keys

GET /api/v1/user/api-keys
Authorization: Bearer <session_token>

Revoke API Key

DELETE /api/v1/user/api-keys/{key_id}
Authorization: Bearer <session_token>

Authentication Examples

Using API Keys

# Using curl with API key
curl -X GET "http://localhost:5555/api/v1/agents" \
  -H "Authorization: Bearer fw_key_abc123..."

JavaScript/Node.js Example

const response = await fetch('http://localhost:5555/api/v1/agents', {
  headers: {
    'Authorization': 'Bearer fw_key_abc123...',
    'Content-Type': 'application/json'
  }
});

const agents = await response.json();

Python Example

import requests

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

response = requests.get('http://localhost:5555/api/v1/agents', headers=headers)
agents = response.json()

Error Handling

Authentication errors return standard HTTP status codes:

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (authentication required)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found

Error Response Format:

{
    "detail": "Error message describing what went wrong"
}

Common Authentication Errors

🔒 Security Best Practices

Next Steps

Now that you understand authentication, explore the other API endpoints: