API keys (headless access)

Most connections use the interactive OAuth 2.1 flow — you sign in once and your MCP client keeps the connection alive. For headless use — a script, a CI job, or a scheduled agent that has no browser to sign in with — CloudQuell offers API keys: long-lived tokens you send directly as a bearer credential.

Availability

API keys are available on all paid plans. Any member of a paid organization creates and manages their own key under Profile → API access in the CloudQuell app. Organization admins can additionally view and revoke every key in the org under Settings → API keys.

What an API key can do

• Read-only, by design. An API key grants the same read access as an OAuth read scope — querying costs, budgets, anomalies, allocation, and the other read surfaces, scoped to the key’s organization. It cannot perform writes — not even if its owner is an admin. This is a deliberate security property, not a temporary limitation: a key sitting in a script or CI secret store can never change anything if it leaks.
• Sees what you see. A key authenticates as the person who created it — it has your read visibility and stops working automatically if you leave the organization. Each person can have one active key at a time.
• Org-scoped. A key only ever sees its own organization’s data — the same multi-tenancy boundary described in Access, limits & data scope.

Need an automation that makes changes?

Use the interactive OAuth connection instead of an API key — for example, a claude.ai scheduled agent with the CloudQuell connector signed in as you. That path can perform writes (creating budgets, dismissing anomalies, …) with your own role and identity, so changes are permission-checked and attributed to you — with no long-lived write credential to protect.

Creating a key

1. In the CloudQuell app, go to Profile → API access.
2. Click Create API key, give it a recognizable name (e.g. CI pipeline, Claude scheduled agent), and create it.
3. Copy the key immediately — it is shown once and cannot be retrieved again. Store it somewhere secure (a secrets manager or your CI’s secret store).

A key looks like cak_ followed by a long random string. CloudQuell only ever stores a hash of it, never the key itself.

Using a key

Send the key as a bearer token to the MCP endpoint:

POST https://mcp.cloudquell.com/mcp
Authorization: Bearer cak_your_key_here

Point any MCP client that supports a static bearer token at https://mcp.cloudquell.com/mcp with that header. No sign-in, refresh, or client registration is required — the key is the credential.

Lifetime & revocation

• Expiry. A key is valid for one year from creation. The expiry date is shown next to your key in Profile → API access.
• Regenerate to rotate. Because you have one key at a time, use Regenerate to roll it — this issues a new secret and invalidates the old one immediately.
• Revoke anytime. Revoke your key to disable it immediately — the next request that uses it is rejected. An organization admin can also revoke any member’s key from Settings → API keys (for example, when offboarding someone).
• Last used. Each key shows when it was last used, so you can spot and revoke stale or unexpected keys.

Keeping keys safe

• Treat a key like a password. Anyone holding it can read your organization’s cost data.
• Never commit a key to source control or paste it into a shared channel. Use a secrets manager or your CI/CD secret store.
• You have one key at a time — if you need to rotate it, use Regenerate and update anything that used the old key.
• If a key is exposed, revoke or regenerate it immediately.