# Authentication and project environments

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

Canonical guide: <https://engine.neraperla.com/docs/authentication>

Raw Markdown: <https://engine.neraperla.com/docs/raw/authentication.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

## Authenticate public API calls

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

```bash
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 type | Console choice | Acts in | Use it when |
|---|---|---|---|
| Project key | **This project** | Its own project, always. | One application or environment uses one project. Start here. |
| Company-level key | **Company (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**.

```bash
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](https://engine.neraperla.com/docs/projects) and [Billing and auto-recharge](https://engine.neraperla.com/docs/billing).

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](https://engine.neraperla.com/docs/agent-setup) 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

| Code | Status | Meaning | Action |
|---|---:|---|---|
| `missing_api_key` | 401 | The Bearer header is absent. | Add `Authorization: Bearer ...`. |
| `invalid_api_key` | 401 | The credential is malformed, unknown, or revoked. | Load an active key from the correct secret. |
| `expired_api_key` | 401 | The key passed its configured expiry. | Rotate to a new active key. |
| `project_required` | 400 | A company-level key made a request that needs a project without naming one, and has no default project. | Send the `Blackpearl-Project` header. |
| `forbidden` | 403 | A 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_archived` | 403 | The 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_found` | 404 | No project with that id or slug exists in your organization. | Check the id or slug, or list projects with `GET /v1/projects`. |
| `not_found` | 404 | The 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](https://engine.neraperla.com/docs/errors) and discover enabled features with [Capabilities and entitlements](https://engine.neraperla.com/docs/feature-flags).

The capabilities request uses OpenAPI operation `capabilities_v1_capabilities_get` and schema `PublicCapabilitiesResponse`.
