Authentication

Every v1 call is a Bearer token on https://www.brainpercent.app/api/v1. Keys are minted in the app. A key cannot create another key.

01Bearer token

Send Authorization: Bearer bp_… on every request.

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

02Key format

bp_ plus 64 hex characters. Shown once at creation. The server stores a SHA-256 hash, so a lost key cannot be recovered. Revoke it and mint another.

03Creating keys

Mint and revoke on Developer settings. Those routes read the signed-in session cookie. A Bearer header against /api/v1/api-keys does not authenticate, and the body is a flat { "error": "…" }, not the envelope below.

A key created without an explicit permissions list gets ["read"]. Every write then returns 403. You can hold ten active keys.

04Permissions and scopes

A request needs both the HTTP permission and the resource scope.

05Error 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"
  }
}

06Response headers

07Rate limits

Per API key, not per account. Generation still costs credits.

08CORS