Authentication

Bearer Token

Include your API key in the Authorization header with every request:

curl https://www.brainpercent.app/api/v1/articles \
  -H "Authorization: Bearer bp_your_api_key_here"

Key Format

API keys follow the format: bp_ followed by 64 hexadecimal characters (67 characters total).

Keys are shown only once at creation. The server stores a SHA-256 hash, so a lost key cannot be recovered. Revoke it and create a new one.

Creating API Keys

Create and revoke keys on the Developer Settings page in your dashboard. The key management routes are session-authenticated, meaning they read your signed-in browser cookie, so there is no way to create a key from a script using another key.

A key created without an explicit permissions list gets ["read"], and every write endpoint will return 403 for it. You can hold at most 10 active keys.

Error Codes

Every Bearer endpoint returns the same error envelope:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

Response Headers

Every Bearer response carries these headers:

Rate Limits

Rate limits are enforced per API key and depend on your plan:

Permissions

API keys can be created with specific permissions that control what operations are allowed. The default is ["read"]:

Scopes

Scopes restrict which resource types an API key can access:

Key Rotation

Best practices for rotating API keys:

• Create a new key with the same permissions and scopes before revoking the old one
• Update your application configuration to use the new key
• Verify the new key works by making a test request
• Revoke the old key from Developer Settings, revocation is session-authenticated and cannot be scripted with an API key
• Set key expiration (expires_in_days) to enforce periodic rotation
• Use separate keys for different environments (development, staging, production)

CORS

Cross-Origin Resource Sharing (CORS) is configured for the API: