API Keys

Create, list, and manage your API keys programmatically.

API key endpoints use session authentication (not API key auth) since they manage keys themselves. Each user can have a maximum of 10 active keys. Keys follow the format bp_ + 64 hex characters (67 characters total). Keys are SHA-256 hashed on the server and are shown only once at creation — store them securely.

Method	Endpoint	Description
`POST`	/api/v1/api-keys	Create a new API key
`GET`	/api/v1/api-keys	List all API keys
`DELETE`	/api/v1/api-keys/:id	Revoke an API key

POST/api/v1/api-keys

Create a new API key. The key value is returned only in this response — store it securely. Requires session authentication (not API key auth). Maximum 10 active keys per user.

Request Body

Name	Type	Required	Description
name	string	Required	Human-readable label for the key (1-100 characters)
permissions	string[]	Required	Permissions to grant: read, write, delete
scopes	string[]	Optional	Resource scopes to restrict access: articles, social, projects, user. Omit for all scopes.(default: `all`)
expires_in_days	integer	Optional	Key expiration in days (1-365). Omit for no expiration.

Request

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

201Response

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "My App Key",
    "key": "bp_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "key_prefix": "bp_a1b2",
    "permissions": [
      "read",
      "write"
    ],
    "scopes": [
      "articles",
      "social",
      "projects",
      "user"
    ],
    "expires_at": "2026-07-01T00:00:00Z",
    "created_at": "2026-02-01T12:00:00Z"
  }
}

GET/api/v1/api-keys

List all API keys for your account. Returns masked key prefixes, permissions, scopes, and usage metadata. Requires session authentication.

Request

curl https://brainpercent.app/api/v1/api-keys \
  -H "Cookie: session=your_session_cookie"

200Response

{
  "success": true,
  "data": [
    {
      "id": "key_abc123",
      "name": "My App Key",
      "key_prefix": "bp_a1b2",
      "permissions": [
        "read",
        "write"
      ],
      "scopes": [
        "articles",
        "social"
      ],
      "created_at": "2026-01-15T10:00:00Z",
      "last_used_at": "2026-02-01T08:30:00Z",
      "expires_at": "2026-04-15T10:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "CI/CD Pipeline",
      "key_prefix": "bp_c3d4",
      "permissions": [
        "read"
      ],
      "scopes": [
        "articles",
        "projects"
      ],
      "created_at": "2026-01-20T14:00:00Z",
      "last_used_at": null,
      "expires_at": null
    }
  ]
}

DELETE/api/v1/api-keys/:id

Permanently revoke an API key. This action cannot be undone — any application using this key will immediately lose access. Requires session authentication.

Request

curl -X DELETE https://brainpercent.app/api/v1/api-keys/key_abc123 \
  -H "Cookie: session=your_session_cookie"

200Response

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "revoked": true,
    "revoked_at": "2026-02-01T12:00:00Z"
  }
}

Permission Reference

Permission	Allows	Example Endpoints
`read`	Retrieve resources (GET requests)	GET /articles, GET /projects, GET /user/credits
`write`	Create and modify resources (POST/PUT)	POST /articles/generate, POST /social/generate
`delete`	Remove resources (DELETE requests)	DELETE /api-keys/:id

Scope Reference

Scope	Endpoints Covered
`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.