Authentication and project environments

Protect project and company-level Bearer keys and isolate environments or clients in projects.

Authenticate public API calls#

Every /v1 operation requires an API key as an HTTP Bearer credential:

curl "$BLACKPEARL_API_BASE_URL/v1/capabilities" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY"

The API's OpenAPI document defines one global HTTP Bearer security scheme. Do not send the key as a query parameter or JSON field.

Choose a key type#

There are two kinds of API key. Both perform real work and record real usage, and neither has a test mode.

Key typeConsole choiceActs inUse it when
Project keyThis projectIts own project, always.One application or environment uses one project. Start here.
Company-level keyCompany (all projects)The project each request names, or the key's default project.One integration runs work in several projects, for example one per client. It can also create projects and manage their allowances and limits over the API.

Owners and administrators create both kinds under API keys. A company-level key holds authority over every project in your organization, so protect it like an administrator credential.

Name the project with a company-level key#

A company-level key finds the project for each request in this order:

  1. The Blackpearl-Project request header, set to the project's id or slug.
  2. For a request about one job, campaign, or audience (for example GET /v1/jobs/{job_id} or a prospecting continuation), the project that owns it. Polling therefore needs no header.
  3. The key's default project, if one was chosen when the key was created. The default choice is None.
curl "$BLACKPEARL_API_BASE_URL/v1/capabilities" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Blackpearl-Project: client-a"

When none of these supplies a project, a request that creates work or reads project data (including GET /v1/capabilities and GET /v1/usage) fails with 400 project_required. Company-wide requests need no project: the projects and limits operations (/v1/projects and /v1/limits), GET /v1/charges (every project unless you narrow it), and GET /v1/pricing-estimates.

A project key may send Blackpearl-Project only with its own project's id or slug; any other value returns 403 forbidden, whether or not that project exists.

Projects are environments or clients#

A project is the isolation boundary for keys, ownership, usage attribution, quotas, budgets, and allowances. Create separate development, staging, and production projects when those workloads must not affect each other.

A project can also be one of your clients. With a company-level key you create a project per client, give each its own allowance, daily and monthly limits, and default brand, and read what each was charged. Your company keeps one prepaid balance. See Managing your clients with projects and Billing and auto-recharge.

An archived project runs no work, and its project keys are refused with 403 project_archived. It is read-only, not hidden: a company-level key that sends no Blackpearl-Project header can still read its jobs, results, campaigns, and audiences by id, but can't change them or start work in it.

A key prefix does not change execution behavior: every hosted request performs real capability work and records real usage. Automated tests should inject explicit test doubles at integration boundaries or target an isolated gateway configured with test services.

Create, store, and rotate keys#

For AI sessions, the agent setup flow delivers a key directly to the agent after you approve in the browser. This avoids copying credentials into chat.

  • Create a key from API keys in the console and copy it immediately; the secret is shown once and stored hashed.
  • Store the value in a server-side secrets manager and expose it to the process as BLACKPEARL_API_KEY.
  • Never commit a key, log it, paste it into support tickets, or embed it in browser or mobile code.
  • Rotate without downtime by creating and deploying a replacement before revoking the old key.
  • A revoked or expired key stops authenticating immediately.

Authentication and project failures#

CodeStatusMeaningAction
missing_api_key401The Bearer header is absent.Add Authorization: Bearer ....
invalid_api_key401The credential is malformed, unknown, or revoked.Load an active key from the correct secret.
expired_api_key401The key passed its configured expiry.Rotate to a new active key.
project_required400A company-level key made a request that needs a project without naming one, and has no default project.Send the Blackpearl-Project header.
forbidden403A project key named another project, or called an operation only a company-level key can use.Use the project's own key or a company-level key.
project_archived403The key's project, the project named by the header, or the company-level key's default project is archived.Use an active project, or restore it with a company-level key.
project_not_found404No project with that id or slug exists in your organization.Check the id or slug, or list projects with GET /v1/projects.
not_found404The job, campaign, or audience doesn't exist where the key can see it: in your organization for a company-level key, in its own project for a project key.Check the id and the key.

These are configuration failures, not transient failures. Do not retry them without changing the credential or project. See the complete error and retry matrix and discover enabled features with Capabilities and entitlements.

The capabilities request uses OpenAPI operation capabilities_v1_capabilities_get and schema PublicCapabilitiesResponse.