Authentication

API keys

All requests to the Aidelly Public API require a bearer token:

Authorization: Bearer aidelly_live_xxx

API keys are created in Account Settings → API Keys. Each key has:

• A name for identification
• A set of scopes that limit what the key can do
• An optional expiry date

Keys are shown once at creation. Store them in a secrets manager (AWS Secrets Manager, Vault, GitHub Secrets, etc.) — never in source code or client-side bundles.

Available scopes

Create keys with the minimum scopes needed for your integration.

Workspace and brand headers

Most endpoints require workspace context:

x-aidelly-workspace-id: <workspace-uuid>
x-aidelly-brand-id: <brand-id>        # optional but recommended

Omitting x-aidelly-brand-id falls back to the workspace's default brand. Some listing endpoints (e.g., GET /posts) accept workspace-only scope.

Find your IDs under Account Settings → API Keys.

MCP OAuth

When using Aidelly via MCP with ChatGPT or Claude connectors, each end user authenticates through OAuth. The MCP server issues per-user Aidelly API keys scoped to their account. See MCP OAuth flow for details.

Key rotation

To rotate a key:

1. Generate a new key with the same scopes
2. Update your integration to use the new key
3. Revoke the old key in Account Settings

Revoking a key immediately invalidates it. Any in-flight requests using the old key return 401 PUBLIC_API_KEY_INVALID.

Security best practices

• Use environment variables — never hardcode keys in source files
• Scope keys minimally — posts:write only if you write posts
• Set expiry dates on keys used in third-party integrations
• Rotate keys on team member offboarding
• Monitor X-RateLimit-* response headers to detect unexpected usage