Authentication and project environments
Protect project-scoped Bearer keys and isolate development, staging, and production work.
Authenticate public API calls#
Every /v1 operation requires a project-scoped 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.
Projects are environments#
A project is the isolation boundary for keys, ownership, usage attribution, quotas, and budgets. Create separate development, staging, and production projects when those workloads must not affect each other.
There is one supported key type. A 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#
- 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 failures#
| Code | Meaning | Action |
|---|---|---|
missing_api_key | The Bearer header is absent. | Add Authorization: Bearer .... |
invalid_api_key | The credential is malformed, unknown, or revoked. | Load an active key from the correct secret. |
expired_api_key | The key passed its configured expiry. | Rotate to a new active key. |
project_archived | The credential belongs to an archived project. | Use a key from an active project. |
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.