Authentication¶

All documented API operations require a project API key. The public OpenAPI document is the only unauthenticated endpoint. Send the key as a Bearer token in the Authorization header.

Authorization: Bearer bfk_<project_api_key>

Create keys in Agate: open the project, select its API tab, then choose New access key. A key belongs to that project only, so {project_slug} must identify the same project. Project API keys are accepted only by /public/v1 endpoints; they cannot authenticate Agate, Stylebook, or other internal API routes.

The full secret is displayed once, immediately after creation. Copy it to a password manager or secret store before closing the dialog; Backfield cannot show it again.

Key types and scopes¶

Key type	Scopes	Use when
User	`read` (always)	Read-only integrations from a user account
Service	`read` (always) plus optional `runs:trigger`	Server-side automation; required to trigger runs

read — query articles, mentions, entities, and other read routes.
runs:trigger — call POST …/runs. May only be minted on service keys (org-admin gated). Get run works with any project key that can access the project.

Do not expose API keys in browser code, mobile apps, logs, or public repositories. Rotate keys if they are shared accidentally.

Personal keys are owned by the user who created them. Their owner can rotate or revoke them; organization administrators can also revoke them. On every request, Backfield confirms that the owner is enabled, still belongs to the project's organization, and still has access to the project. Disabling the owner, removing the organization membership, or removing all project access invalidates the key on the next request.

Service keys are ownerless credentials managed by organization administrators for trusted automation. Legacy ownerless personal keys are rejected.

For a safe rotation, create a replacement key, update every client and verify requests with the replacement, then revoke the old key. Revoking first causes clients using the old key to receive 401 responses.

Request IDs¶

Every Public API response includes an X-Request-ID header. You may send your own X-Request-ID; otherwise Backfield generates one and returns it. Record this value when troubleshooting and include it with a support request so the server-side request can be traced.

Error bodies also include the same value in request_id. See Errors.

OpenAPI and Playground¶

The public OpenAPI document is available without authentication at https://api.{organization_slug}.backfield.news/public/v1/openapi.json. It declares this Bearer-token scheme and contains only public endpoints.

The hosted API Playground keeps a key in tab-scoped session storage. It survives page reloads and is removed when you clear it, sign out, or close the tab under the browser's normal session-storage lifecycle. This is suitable for interactive exploration on a trusted device, but application integrations should still keep keys in a server-side secret store.

Example¶

curl "https://api.{organization_slug}.backfield.news/public/v1/projects/general/articles/search?q=budget" \
  -H "Authorization: Bearer bfk_your_project_api_key"

Errors¶

Status	When
`401`	Missing, invalid, revoked, or no-longer-authorized API key
`403`	Key is valid but bound to a different project, or lacks a required scope

If a project or resource cannot be found for your key, the API may return 404. See Errors.

For unexpected errors, inspect the response's X-Request-ID header and retain it with the status code and response body.