API Key Security

Using the older navigation? The workspace navigation guide maps Send, Measure, and Build to the existing pages and legacy labels.

API keys are long-lived, tenant-scoped credentials for the partner API. Keep them server-side and manage them under Build → API keys.

Create a Key

1. Sign in and open Build → API keys.
2. Confirm the LIVE/TEST workspace switch matches the environment you intend to call.
3. Select New API key.
4. Give the key a descriptive label and choose its allowed scope.
5. Copy the secret immediately. Connect shows it once.

The Connect credentials card labels the workspace identifier Account ID. In API and environment configuration this value maps to tenant_id / CONNECT_TENANT_ID.

Connect-minted keys use an ac_live_… or ac_test_… prefix. Treat the suffix as opaque; do not validate a fixed length, UUID layout, or hex alphabet in your application. Tenant IDs are opaque tenant_* workspace slugs, not UUIDs.

LIVE and TEST behavior

TEST is a credential and delivery mode within a workspace; it is not a separate data plane. Use an isolated workspace and non-production deployment for automated fixtures. New TEST launches and their assessment events remain excluded from LIVE Skills and Value calculations. Historical records without a recorded mode cannot establish prior separation.

TEST keys are for development and integration testing. TEST learners are never billed. Each workspace can serve up to 25 active TEST learners per rolling 30 days (the Free allowance); the next new TEST learner gets 402 ACTIVE_LEARNER_CAP_REACHED. Use a LIVE key for production learners.

Skills, capability, graph, CALE and xAPI statement API families currently return 403 TEST_MODE_UNSUPPORTED for TEST credentials. The corresponding dashboard surfaces show an unavailable state in TEST mode. Use an authorized LIVE key only for intended LIVE evidence; changing modes does not bypass subscription or role requirements.

Scopes

• public_api: normal customer and partner integrations
• internal_product: approved product-to-product callers
• admin: privileged operational callers

You can create public_api keys yourself. Allure Connect issues internal_product and admin keys; self-serve requests for them return 403 API_KEY_SCOPE_NOT_ALLOWED. The exception is a trusted issuer: an Allure Connect platform operator, or a workspace that Allure Connect has grandfathered for privileged keys, may still create them.

There is no generic read or write scope. Each route declares its accepted scopes in OpenAPI.

Send a Key

Prefer Bearer authentication:

curl https://app.allureconnect.com/api/v1/packages \
  -H "Authorization: Bearer $CONNECT_API_KEY"

X-API-Key is also supported. If both headers are sent, Bearer wins.

Never send an API key to /api/customer/*; those routes require a signed-in Clerk browser session. Never expose a key in browser JavaScript, a launch URL, logs, screenshots, support tickets, or source control.

Store Keys

Use a server-side secret manager or protected environment variable:

const apiKey = process.env.CONNECT_API_KEY;
if (!apiKey) throw new Error('CONNECT_API_KEY is not configured');

Recommended controls:

• separate LIVE and TEST keys;
• one key per integration or deployment boundary;
• least-privileged scope;
• restricted access to production secrets;
• request-log monitoring under Build → Request logs;
• immediate rotation after suspected exposure.

Rotate or Revoke

The Rotate row action creates a replacement and revokes the old key atomically. It preserves the stored key's scope, LIVE/TEST mode, expiry, permissions and client restrictions. Copy the replacement secret from the one-time reveal and update consumers immediately; the old key stops working as soon as rotation succeeds.

For a staged replacement with an overlap period, use separate create and revoke operations in Build → API keys:

1. Create a replacement key.
2. Put the new secret in every consuming system.
3. Verify requests appear under Request logs with the replacement key.
4. Revoke the old key from the dashboard.

There is no public POST /api/admin/api-keys endpoint. There is no public DELETE /api/admin/api-keys/{id} endpoint. Automation should use an approved internal provisioning workflow rather than copying dashboard-only routes.

Revoked secrets return:

{
  "error": "API key required",
  "code": "API_KEY_REQUIRED"
}

Incident Checklist

If a key may be compromised:

1. Revoke it in the dashboard.
2. Create and securely distribute a replacement.
3. Review Request logs for unexpected paths, status codes, and timestamps.
4. Rotate any downstream secret that was stored beside it.
5. Record the incident without pasting the secret into the ticket.

See the API reference and error codes.