API keys

Creating an API key

Only organization owners and admins can create API keys. To create one:

1. Go to your organization's Settings page.
2. Scroll to the API Keys section.
3. Click "Create API Key."
4. Fill in the details: name, scopes, optional project restrictions, and expiration.
5. Click "Create."

After creation, the full key is shown exactly once. Copy it immediately and store it somewhere secure (a secrets manager or environment variable). You won't be able to view the full key again. If you lose it, you'll need to create a new one.

Keys follow the format qtrl_live_<random-string>. In the key list, only the first few characters are shown as a prefix for identification.

Scopes

Every API key has one or more scopes that control what it can do. Give each key only the permissions it actually needs:

• Read allows viewing projects, tests, test runs, tasks, and execution results. Use this for monitoring dashboards or read-only integrations.
• Write includes everything read can do, plus creating and updating resources like tests, test runs, and tasks. This is what most CI/CD integrations need.
• Admin grants full access, including administrative operations. Use this sparingly and only when necessary.

Scopes are hierarchical: admin implies write, and write implies read. You can combine scopes, but in practice you'll usually just pick the single level you need.

Project scoping

By default, an API key has access to all projects in the organization. If you want to restrict a key to specific projects (for example, giving a CI pipeline access to only the project it deploys), you can select "Specific projects" during creation and pick which ones.

A project-scoped key that tries to access a different project gets a 404 response (not 403), so it can't even confirm the other project exists.

Expiration

When creating a key, you choose an expiration policy:

• Never means the key stays valid until you revoke it manually.
• 30 days or 90 days sets an automatic expiration date.

Expired keys stop working immediately. If you need to replace an expiring key, create a new one before the old one expires, update your integrations, then revoke the old key.

Using an API key

Include the key in the Authorization header of your HTTP requests:

Authorization: Bearer qtrl_live_your_key_here

For example, with curl:

curl -H "Authorization: Bearer qtrl_live_abc123..." \
  https://app.qtrl.app/api/v1/projects

If the key is missing, invalid, revoked, or expired, the API returns a 401 error with a message explaining the issue.

For the full list of available endpoints, see the API overview and the interactive API reference.

Revoking a key

To revoke a key, find it in the API Keys section of organization settings and click the revoke button. Revocation takes effect immediately: any request using that key gets a 401 response.

Revoked keys can't be reactivated. If you revoked a key by mistake, create a new one and update your integrations.

Best practices

• Create separate keys for each integration or service. If one gets compromised, you can revoke just that key without disrupting everything else.
• Use the narrowest scope possible. A CI pipeline that only triggers test runs needs write access, not admin.
• Scope keys to specific projects when you can. It limits the blast radius if a key leaks.
• Set an expiration for keys used in less-trusted environments. Rotate them before they expire.
• Never commit API keys to source control. Store them in your CI/CD system's secret management or a dedicated vault.