Docs/Authentication

Authentication

Learn how to authenticate your API requests with commandAGI.

Overview

All API requests to commandAGI require authentication using Bearer tokens. API keys are scoped to your account and can optionally be restricted to specific projects.

Security Best Practices

Never expose API keys in client-side code or public repositories
Use environment variables to store API keys
Create separate keys for development and production
Rotate keys periodically and revoke unused keys

Bearer Token Authentication

Include your API key in the Authorization header of every request using the Bearer scheme.

Header Format

Authorization: Bearer to_your_api_key_here

Example Request

curl -X GET https://api.commandAGI.com/v1/profiles \
  -H "Authorization: Bearer cagi_abc123def456ghi789jkl012mno345pqr678stu901vwx"
  -H "Content-Type: application/json"

API Key Format

API keys follow a consistent format for easy identification:

to_<48 hex characters>

to_ - Prefix identifying commandAGI keys
48 hex chars - Cryptographically random identifier

Roles and Permissions

Access to API endpoints is controlled by user roles. Your API key inherits the roles assigned to your account.

Role	Permissions
dev	Create and manage projects, profiles, and frames you own
admin	Full access to all resources across all users
annotator	Can annotate frames on active marketplace projects

Error Handling

Authentication errors return consistent JSON responses with error details.

Error Response Format

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

401Unauthorized

Invalid or missing API key

Solution: Check that your API key is correct and included in the Authorization header

403Forbidden

Valid key but insufficient permissions

Solution: Ensure your account has the required role (dev or admin) for this endpoint

429Too Many Requests

Rate limit exceeded

Solution: Wait before retrying. Consider upgrading your plan for higher limits

Keep Your Keys Secret

API keys grant full access to your account resources. If you believe a key has been compromised, revoke it immediately in your project settings and create a new one.