API Keys

API keys let scripts, integrations and embedded dashboards call the Querri API. Each key has a type that sets what it can do, an expiry date, and a rate limit. You can revoke it at any time.

Who can use this: organization admins. Open Settings from your avatar menu, then API Keys in the Security group.

1. Create API Key: make a new key.
2. Scopes: the key’s type, or how many scopes it has.
3. Expires: when the key stops working.
4. Status: whether the key is active, revoked or expired.

The key list

Column	What it shows
Name	The key’s name, with who created it underneath
Key	The start of the key, so you can tell keys apart
Scopes	The key type (Data Access, Full Access or Embed), or how many scopes a custom key has
Created, Last Used	When it was made, and when it was last used, or Never
Expires	When it stops working
Status	active, revoked or expired

The trash icon at the end of an active key’s row revokes it.

Create a key

1. Click Create API Key.
2. Choose a type:
   • Data Access: read your data from another tool. Its one scope is data:read.
   • Full Access: every API endpoint. The card says “Use with caution.”
   • Embed: create embed sessions for dashboards you show your customers.
   • Custom: choose exactly which permissions the key gets.
3. Fill in the details:
   • Key Name, such as the integration it’s for.
   • Permissions (Custom only): scopes grouped as Data, Embed, Users, Policies, Projects, Dashboards, Sources, Files, Sharing, Keys, Usage and Audit.
   • Expires In: 30, 60, 90 or 180 days, or 1 year. The default is 90 days, and there’s no option for a key that never expires.
   • Rate Limit (per min): 60 by default, anywhere from 1 to 10,000.
   • IP Allowlist (optional): one IP address or CIDR range per line. Leave it empty to allow requests from anywhere.
4. Click Create Key.
5. Copy the secret. The page warns This secret will only be shown once, and you won’t be able to see it again.
6. Tick I’ve saved my key securely, then click Done. The dialog won’t close until you tick it.

1. Data Access: read your data from another tool.
2. Embed: create embed sessions for dashboards.
3. Custom: choose each permission yourself.
4. The Full access chip: marks the type that can call every endpoint.

1. Source Scope: pick sources. It doesn’t limit the key yet; see the note below.
2. Expires In: how long the key works.
3. Rate Limit (per min): how many calls a minute it can make.
4. IP Allowlist: the addresses it can be used from.

The last screen also has a Quick Start with cURL, Python, JavaScript and Querri SDK examples, and your Organization ID, which every request needs.

1. This secret will only be shown once: copy it before you close the dialog.
2. Quick Start: example calls in cURL, Python, JavaScript and the Querri SDK.
3. I’ve saved my key securely: tick it to close the dialog.

Source Scope doesn’t limit a key yet

When a key can read data, step 3 also shows Source Scope, where you can pick sources. Picking sources there doesn’t currently limit which sources the key can read. A key made with a source scope in Settings can still read every source the admin who created it can. Don’t rely on it to keep a key away from sensitive tables.

Use a key

Send the secret as a bearer token, along with your organization ID:

curl -H "Authorization: Bearer <your secret>" \
     -H "X-Tenant-ID: <your organization id>" \
     https://app.querri.com/api/v1/projects

See Authentication and the API reference for scopes and endpoints.

What a key can reach

A key can only take the actions its scopes allow.

Its rows aren’t filtered by the access policies of the admin who created it. Only policies assigned to the key itself apply, and there’s no way to assign one yet, in Settings or through the public API. For which sources it can read, see the Source Scope note above.

The API can also tie a key to one workspace or one user. Settings doesn’t offer those options. See Authentication.

Revoke a key

Click the trash icon on the key’s row, then Revoke key in the confirmation. The key stops working immediately, and it can’t be switched back on.

What’s recorded

Creating a key, revoking it, and using it are written to the Security audit log. Use is recorded at most once a minute per key.

Good habits

• Give each integration its own key, so you can revoke one without breaking the rest.
• Pick the narrowest type that works. Save Full Access for when nothing else will do.
• Choose the shortest expiry you can live with, and set a reminder to replace the key before it runs out.
• Add an IP allowlist when the calls come from fixed addresses.
• To rotate a key, create the new one, switch your integration over, then revoke the old one.
• Check Last Used and the audit log for keys nobody should be using.
• Keep secrets out of source control. Use environment variables or a secrets manager.

Next steps

• Authentication: headers, scopes and errors
• Access Policies: row filters
• Audit Log: key creation, use and revocation