Authentication

All API requests require a Bearer token in the Authorization header.

Bearer Token

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

curl https://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 — lost keys cannot be recovered and must be regenerated.

Creating API Keys

Create API keys from the Developer Settings page in your dashboard, or via the API:

curl -X POST https://brainpercent.app/api/v1/api-keys \
  -H "Cookie: your_session_cookie" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App Key", "permissions": ["read", "write"]}'

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Key lacks required permission
429	RATE_LIMIT_EXCEEDED	Too many requests
402	INSUFFICIENT_CREDITS	Not enough credits for the operation

429Rate limit response

{
  "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"
  }
}

Permissions

API keys can be created with specific permissions that control what operations are allowed:

Permission	HTTP Methods	Description
`read`	GET	List and retrieve resources — articles, social content, projects, credits, usage
`write`	POST, PUT	Create and modify resources — generate articles, generate social content, publish
`delete`	DELETE	Remove resources — revoke API keys

Scopes

Scopes restrict which resource types an API key can access:

Scope	Endpoints
`articles`	/api/v1/articles/*, /api/v1/articles/generate, /api/v1/articles/:id/status
`social`	/api/v1/social/content/*, /api/v1/social/generate, /api/v1/social/publish
`projects`	/api/v1/projects/*
`user`	/api/v1/user/credits, /api/v1/user/usage

A request is authorized only when the API key has both the required permission AND the matching scope. For example, generating an article requires the write permission and the articles scope.

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 via DELETE /api/v1/api-keys/:id
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:

Header	Value
Access-Control-Allow-Origin	* (all origins)
Access-Control-Allow-Methods	GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers	Authorization, Content-Type, X-Request-Id
Access-Control-Max-Age	86400 (24 hours)

While CORS allows browser-based requests, avoid exposing your API key in client-side code. Use a backend proxy or serverless function to keep your key secure.