API keys and authentication

Use this guide when API key controls are missing or an API request returns 400, 401, 403, 404, 402, 429, or 503. Work from the HTTP status and Problem Details body instead of changing credentials at random.

Never send Parix support a complete API key, bearer token, authentication header, or secret-bearing request body.

Run this check first

Call the session endpoint against the same base URL as the failing request, using exactly one authentication header:

curl -i "$PARIX_BASE_URL/api/v1/session" \
  -H "x-api-key: $PARIX_API_KEY"

For OAuth/CLI access tokens, use:

curl -i "$PARIX_BASE_URL/api/v1/session" \
  -H "Authorization: Bearer $PARIX_ACCESS_TOKEN"

On success, compare the returned organization, scopes, authentication type, and API key metadata with the target request. On failure, retain the HTTP status, title, detail, instance, and any field errors.

API key settings returns 404 or controls are unavailable

Symptom. Opening an API key URL returns a page not found, or the page loads but create, rotate, or delete controls are unavailable.

Likely cause. API key settings are global rather than organization-slug routes, or your membership is not an organization owner/administrator.

Exact checks.

1. Inspect the browser path. The supported routes are /settings/api-keys and /settings/api-keys/generate.
2. Remove an organization slug such as /acme/settings/api-keys from the beginning of the path.
3. Confirm that you are signed in to the intended Parix account.
4. Ask an existing owner/admin to confirm your role in the organization that will own the key.

Recovery. Open Settings > API keys from the global settings navigation. An owner/admin can create a key with a 2–40 character name and either an all-databases or specific-database boundary. Copy the secret immediately; it is shown only once.

When to contact support. Contact Parix support through the channel included with your plan if the canonical global route fails for multiple owners/admins. Include the organization slug, UTC time, browser path, and screenshot with secrets removed.

A request returns 401 Authentication required

Symptom. /api/v1/session or another API endpoint returns HTTP 401 with Authentication required.

Likely cause. The credential is missing, truncated, invalid for this environment, expired, or disabled. A rotated key's old secret is disabled immediately.

Exact checks.

1. Confirm that the request sends one of x-api-key: <key> or Authorization: Bearer <token-or-api-key>—not a query parameter.
2. For an API key, prefer x-api-key while diagnosing and confirm that the stored value begins with the expected px_ prefix without printing the remainder.
3. Check for copied quotation marks, whitespace, line breaks, or a secret-manager template that did not expand.
4. Confirm that $PARIX_BASE_URL is the same environment in which the key was created.
5. In Settings > API keys, check whether the key metadata still exists and whether it was disabled, expired, or rotated.

Recovery. Correct the header or environment. If the one-time secret was not stored, rotate the visible key or create a replacement with the intended boundary, save the new secret, update the consuming service, and confirm /api/v1/session before removing obsolete metadata. Rotation preserves the key metadata/boundary and disables the old credential.

When to contact support. Escalate when a newly issued key fails /api/v1/session in its creation environment after the checks above. Provide the key name or ID, not its secret, plus the request time, environment, request path, and Problem Details body.

A request returns 403 for a missing scope

Symptom. Authentication succeeds, but the API reports that db:read or db:write is required.

Likely cause. An OAuth/CLI token lacks the endpoint's granted scope. API keys carry both database scopes, so a 403 for an API key is more commonly a resource-boundary issue covered in the next section.

Exact checks.

1. Read scopes from GET /api/v1/session.
2. Classify the operation:
   • database list/get and TigerBeetle lookup, history, or query operations require db:read;
   • catalog/create/delete and TigerBeetle create_accounts/create_transfers require db:write.
3. Confirm the credential type returned by the session endpoint instead of inferring it from the Authorization header.

Recovery. Reauthorize the OAuth/CLI client with the required scope or use an appropriately governed API key. Do not broaden a token beyond the integration's actual needs.

When to contact support. Escalate if /session shows the required granted scope but the same credential receives a missing-scope response. Include sanitized session output, request method/path, UTC time, and Problem Details.

A request returns 403 for the API key boundary

Symptom. A valid API key can call /session, but creation/deletion is refused, or a database operation says the key is restricted to a different database.

Likely cause. The key uses the specific_database boundary. That key can list its one bound database and operate only on that database; it cannot call organization-wide catalog, create, or delete operations.

Exact checks.

1. Inspect the key boundary and database metadata in /api/v1/session.
2. Compare the bound database UUID with {databaseId} in the failing route.
3. If the route is GET /api/v1/catalog/create, POST /api/v1/databases, or DELETE /api/v1/databases/{databaseId}, confirm that the key is all-databases scoped.
4. Confirm the key and target database belong to the same environment and organization.

Recovery. Use the bound database UUID for database-specific work. For organization-wide lifecycle automation, have an owner/admin create an all-databases key and store it separately from application keys. Do not rotate a database-scoped key expecting its boundary to change; rotation preserves its metadata.

When to contact support. Escalate only if session metadata shows the correct all-databases boundary or matching database UUID and access is still refused. Include key ID/name, organization slug, target database UUID, method/path, UTC time, and response body.

A database request returns 404

Symptom. Authentication works, but a database or TigerBeetle route returns not found.

Likely cause. The path contains a display name instead of the database UUID, the UUID belongs to another environment/organization, the database was deleted, or the route/version is incorrect.

Exact checks.

1. Confirm the route starts with /api/v1 and matches a route in the current live OpenAPI document.
2. Call GET /api/v1/databases with the same credential and find the target UUID.
3. For a specific-database key, confirm that the one returned database is the intended target.
4. Compare the API base URL with the dashboard environment where the database is visible.
5. Inspect the database's deletion/decommission state if it was recently removed.

Recovery. Replace the display name or stale identifier with the UUID returned by the list endpoint, and send the request to the matching environment. If the target is outside the credential boundary, use a separately authorized credential rather than exposing it to the current integration.

When to contact support. Escalate when the UUID is visible to the same credential in the list response but its get route immediately returns 404. Include sanitized list evidence, database UUID, organization slug, UTC time, and both request paths.

A request returns 400 Validation Error

Symptom. The API returns HTTP 400 with title: "Validation Error", errors, or fieldErrors.

Likely cause. A required field is missing, an unknown field was supplied to a strict schema, an integer/range is invalid, or a create request contains stale catalog IDs.

Exact checks.

1. Read every entry in errors and fieldErrors; the top-level detail is only a summary.
2. Compare the request with /api/v1/openapi.json from the same environment.
3. For database creation, fetch GET /api/v1/catalog/create again and compare every selected provider, region, cluster configuration, size, storage tier, and storage amount.
4. For TigerBeetle operations, confirm the operation-specific payload shape, required limit, strict field names, numeric ranges, and maximum batch length described in TigerBeetle operations.

Recovery. Correct only the fields named by validation and resubmit once. Update generated clients if their checked-in schema differs from the current environment's OpenAPI document.

When to contact support. Escalate when a body that validates exactly against the same environment's current OpenAPI document is rejected. Include the schema version/retrieval time, sanitized payload, field errors, route, and UTC time.

Authentication succeeds but the request returns 402, 429, or 503

Symptom. /session succeeds, but an otherwise valid lifecycle or TigerBeetle request returns billing required, quota/rate limit, or service unavailable.

Likely cause. This is a plan, billing, shared-placement, or provider availability gate—not an API key failure. Shared Developer enforcement uses the current configured limits rather than constants that clients should embed.

Exact checks.

1. Read the response's status, title, detail, and any billing code, message, or checkoutUrl.
2. Check the database Dashboard and metrics/usage surface for the current plan state.
3. For 429, identify whether the message names a rate, monthly, lifetime, pending-transfer, or other plan boundary.
4. For 503, call GET /api/v1/databases/{databaseId} and confirm the shared placement or dedicated profile state.
5. For create requests, re-read the current catalog rather than switching to a provider that is not offered.

Recovery. Follow a returned billing action when it matches the intended plan. For rate windows, wait for the specified/current window rather than rotating keys. For quota boundaries, reduce usage or change plan through the supported product path. Retry a transient 503 cautiously with backoff; do not create duplicate resources to bypass it.

When to contact support. Escalate a persistent 503 or a plan response that contradicts the dashboard. Include organization slug, database UUID, plan shown, UTC timestamps, request path, response body, and latest workflow/job ID where applicable. Contact Parix support through the channel included with your plan.