API keys

Each key belongs to one workspace and inherits its owner's current permissions there. Create a separate named key for each client so you can replace or revoke it independently.

Create a key

You need the API keys permission in your role.

1. Open Settings > API keys in the workspace the client will use.
2. Select Create key.
3. Enter a name that identifies the client, such as GitHub Actions or Bitbucket Pipelines, then select Save.
4. Select Copy and store the key in the client's secret settings before closing the dialog. The full key is shown only once.

If you lose the value, rotate the key to get a replacement.

Permissions

A personal API key acts with its owner's permissions in the workspace where it was created. Changes to the owner's permissions apply to the key too. The key stops working if its owner no longer belongs to that workspace.

The creation form asks for a name. There is no separate permission or scope selector for each key. A key name identifies its purpose; it does not limit what the key can do.

For Git CI sync, the owner needs workspace file read, write and delete permissions. Database queries require the owner's datasource access separately. See Roles and Groups.

Use a key for Git sync

Store the key as a secret named QUERIO_ACCESS_TOKEN in your CI provider. Use the setup instructions for GitHub Actions or Bitbucket Pipelines.

QUERIO_ACCESS_TOKEN is the secret's name; its value is the key you created in Querio. GitHub uses the Querio app for the repository connection. Bitbucket uses a separate repository access token. Neither of those repository credentials replaces the Querio key used by CI.

For direct API calls, send the key in the Authorization: Bearer header. See API authentication. For CLI environment authentication, see the CLI reference.

Rotate a key

Rotation replaces the secret for an existing key and stops the old value from working immediately. Plan to update every client using that key.

1. Open Settings > API keys and find the key by name.
2. Open its actions menu and select Rotate.
3. Confirm with Rotate key.
4. Copy the replacement value and update the corresponding client or CI secret.

Querio displays the replacement only once. Run the client or CI job to check that it can authenticate again.

Revoke a key

When a client no longer needs access, open the key's actions menu, select Revoke and confirm with Revoke key. Revocation stops the key from working immediately and cannot be undone.

The table shows each key's status and last-used time. Use Edit to change its name.

Authentication problems

• The client cannot authenticate: check that it has the complete key value and that the key has not been rotated or revoked.
• Authentication works but an action is denied: check the owner's current workspace permissions and, for queries, datasource access.
• The client is targeting another workspace: create a key in the intended workspace. A key's workspace cannot be changed by sending a different workspace ID.