API Keys

API Keys

Bourd’s API is fully featured and powers our own client application. Everything you can do in the UI, you can do via the API. API keys let you access your data programmatically and integrate Bourd into whatever system you need.

For the full endpoint reference, see the OpenAPI documentation.

Key Types

Bourd offers two types of API keys, each scoped to a different level of access.

Account Keys (bourd_ak_)

Account keys operate at the account level. They can manage account settings, billing, team membership, and workspace lifecycle — but they cannot access any workspace-scoped resources like prompts, brands, or competitors. If you need to work with workspace data, create a workspace key instead.

Use account keys when you need to:

• Manage billing and subscriptions.
• Invite or remove team members.
• Create, update, or delete workspaces.
• Manage account-level roles.

Account keys can be granted the following permissions (grouped by area):

Area	Permissions
Account	accounts.delete
Roles	account_roles.create, account_roles.update, account_roles.delete, account_roles.view
Billing	billing.update_subscription, billing.update_payment_method, billing.view_invoices, billing.update_billing_info
Team members	users.invite, users.remove, users.assign_account_role, users.view_all_users
Workspaces	workspaces.create, workspaces.delete, workspaces.update

Workspace Keys (bourd_wk_)

Workspace keys are bound to a single workspace at creation time and can only access resources within that workspace. They cover the full range of workspace operations — prompts, brands, competitors, schedules, reports, and more.

Use workspace keys when you need to:

• Trigger prompt runs or manage schedules programmatically.
• Sync brand or competitor data from an external system.
• Build a reporting integration that reads analysis results.
• Grant scoped access to a specific team or external service without exposing other workspaces.

Workspace keys can be granted the following permissions (grouped by area):

Area	Permissions
Workspace	workspace.delete, workspace.settings.update
Members	workspace.members.invite, workspace.members.remove, workspace.members.update_role, workspace.members.list
Prompts	prompts.create, prompts.read, prompts.update, prompts.delete, prompts.run
Brands	brands.create, brands.read, brands.update, brands.delete
Competitors	competitors.create, competitors.read, competitors.update, competitors.delete
Schedules	schedules.create, schedules.read, schedules.update, schedules.delete
Citations	citations.read
Reports	reports.read
Insights	insights.read, insights.create, insights.update, insights.settings.update

When in doubt, use a workspace key. It provides the narrowest access scope and limits the blast radius if a key is compromised.

Creating an API Key

Account Keys

1. Navigate to Account Settings → API Keys.
2. Click Create API Key.
3. Fill in the form:
   • Name (required) — A descriptive label (e.g., “CI Pipeline”, “Data Warehouse Sync”).
   • Description (optional) — Additional context about the key’s purpose.
   • Expiration (optional) — Defaults to 12 months. Maximum is 5 years. You can also create keys with no expiration.
   • Permissions — Select the permissions this key should have. You can only grant permissions that you yourself hold.
4. Click Create.
5. Copy the key immediately. The full key is shown only once and cannot be retrieved later. If you lose it, you will need to create a new key.

Workspace Keys

1. Navigate to Workspace Settings → API Keys within the desired workspace.
2. Follow the same steps as above.

Using an API Key

Include the key in the Authorization header of your HTTP requests:

Authorization: Bearer bourd_ak_abc123...

Authorization: Bearer bourd_wk_abc123...

All API endpoints are documented in the OpenAPI reference, which includes request/response schemas, required parameters, and example payloads.

Permissions

API key permissions mirror the role-based permissions in the application. When creating a key, you select which permissions to grant.

Escalation Prevention

You can only grant permissions that you currently hold. For example, if your role does not include the ability to manage team members, you cannot create an API key with that permission.

Forbidden Permissions

The following permissions cannot be granted to any API key (account or workspace) for security reasons:

• api_keys.create
• api_keys.read
• api_keys.delete

Key management is an administrative action that requires a human session. This prevents a compromised key from being used to create, enumerate, or revoke other keys.

Managing API Keys

Viewing Keys

The API Keys page (in either Account or Workspace settings) shows all active keys with:

• Key hint — The first few characters of the key for identification.
• Last used — When the key was last used to make an API call.
• Expiration status — Whether the key is active, expiring soon, or expired.

Revoking Keys

To revoke a key, click the revoke action on the API Keys page. Revocation is immediate and irreversible. Any requests using the revoked key will receive a 401 Unauthorized response.

Security Best Practices

• Use the principle of least privilege. Grant only the permissions the integration actually needs.
• Set an expiration date. Avoid creating keys that never expire unless absolutely necessary.
• Prefer workspace keys. Use workspace keys over account keys whenever possible to limit scope.
• Rotate keys periodically. Create a new key, update your integration, then revoke the old one.
• Revoke unused keys. If a key is no longer needed, revoke it immediately.
• Never commit keys to source control. Store them in environment variables or a secrets manager.

Troubleshooting

401 Unauthorized

• The key has been revoked.
• The key has expired.
• The key value is incorrect or malformed (check for trailing whitespace or truncation).

403 Forbidden

• You are using an account key on a workspace-scoped endpoint (e.g., /workspaces/{slug}/prompts). Account keys cannot access workspace routes — create a workspace key for the target workspace instead.
• You are using a workspace key on a workspace it is not bound to. Each workspace key is locked to the workspace it was created in.
• The key does not have the required permission for the endpoint. Check the key’s permissions in settings and refer to the permission tables above.

Next Steps

• OpenAPI Reference — Full endpoint documentation.
• Running Analysis — Trigger prompt runs via the API.
• Scheduling Automation — Automate analysis with schedules.