API keys and authentication

Start with the credential and route. Most API failures in Parix are caused by using an organization-scoped settings URL, using a database-scoped key for an organization-wide operation, or calling a write operation with read-only access.

Use this page by matching the symptom first, then checking the route, header, scope, and database identifier.

API key settings route returns 404

API keys live under global settings:

/settings/api-keys
/settings/api-keys/generate

Do not prefix this route with an organization slug. For example, /acme2/settings/api-keys is not the API key page.

Fix: open /settings/api-keys or /settings/api-keys/generate.

Authentication required

Use one of these headers:

x-api-key: <key>
Authorization: Bearer <token-or-api-key>

If a key was just generated, confirm you copied it immediately. The secret is shown once and cannot be recovered from the dashboard later.

Fix: regenerate the key if the original secret was not stored.

Missing scope

Database reads and read-only TigerBeetle operations require db:read. Database creation, deletion, and TigerBeetle create operations require db:write.

Use an all-databases key for organization-wide operations such as database creation. A specific-database key is appropriate after the database exists and the operation targets that same database.

Fix: create a key whose scope matches the API route you are calling.

Wrong database identifier

Dashboard URLs use database names. API URLs use database IDs. Use the database ID shown on the database Dashboard page when calling:

/api/v1/databases/{databaseId}
/api/v1/databases/{databaseId}/tb/{operation}