Authenticate with an API key

An API key authenticates a script, a CI job or an MCP client without an interactive login. It stands in for a person, so treat it like one.

Choose a key or a sign-in

An AI agent on the hosted MCP server can sign in as you instead of using a key. Use sign-in when a person is at the keyboard: the agent acts as you, with your role capped at Member, and stops working when you leave the team. Use a key where nobody can open a browser, such as CI, a headless agent or the local MCP binary, and for anything that should keep working whoever leaves.

Create a key

In the dashboard, go to People and access → API keys and create one. Creating, rotating and revoking keys needs the Admin role. A team can hold 25 usable keys at a time; expired and revoked keys do not count. The full key is shown once, at creation. We store only a hash, so a key you did not copy is gone and you will need a new one.

dbk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

That example is deliberately fake. A real key is 64 random hex characters after the prefix.

Know when a key expires

There are two kinds of key, and API keys lists them separately:

• Standard keys are the ones you create on the API keys page, listed under Scripts and CI. They never expire. One that has not been used for 30 days turns amber, with Revoke beside it.
• Agent keys are made by the connect-your-agent screen and are listed under AI agents. Each one expires 90 days after it was created or last rotated. You cannot choose a different lifetime.

Each agent key shows a bar for what is left of its 90 days and the date it expires. In its last 14 days the row turns amber and offers Rotate right there. An expired key stays in the list until you rotate or revoke it, so nothing that used it disappears from view. A line at the top of the page counts the keys that need you.

See what a key did

Under each key’s name, API keys says what the key last did and when, for example “Created a deployment of Repro Site, via MCP, 20 min ago”. Beside it is the number of requests the key made in the last 7 days. Select that number to open What this key did: every request the key made, newest first and grouped by day, 50 at a time. Anyone on the team with the Member role or above can open it.

• A refused request counts too. It reads “Tried to create a deployment of Repro Site (refused, 403)”, so a key that keeps getting turned away stands out.
• “via MCP” is what the caller said it was. The CLI and the MCP server send an X-Deploybase-Client header, and the page shows it as sent; nothing verifies it. A request without that header, such as a bare curl, shows no client.
• Project names are current. A renamed project shows its new name. One that has since been deleted reads “a deleted project”.
• A rotated key keeps its history. Requests made with the old secret stay listed, under a line that marks when the secret changed, and the row says “Not used since rotation” until the new secret is used.

The record is kept for 90 days. A request made with an expired or revoked key is refused before it is recorded, so it does not appear here. Under very heavy load a few read requests can go unrecorded, so treat the count as a floor, not a bill.

The same history is available over the API, with the Member role, so a key can read it too:

curl https://api.deploybase.eu/api/v1/api-keys/01234567-89ab-cdef-0123-456789abcdef/activity \
  -H "Authorization: Bearer $DEPLOYBASE_API_KEY"

Each event carries phrase, outcome (done, refused or failed), status_code, client and created_at. When next_cursor is not null, pass it back as ?cursor= for the next 50 older requests.

See and revoke signed-in agents

Agents that signed in are listed on the same page, under Signed-in agents. Each row names the agent, where it comes from, who it acts as, when it connected and when it was last used. Anyone on the team can see the list.

• Activity opens What this agent did, the same per-request history a key has, kept for 90 days. It needs the Member role.
• Revoke signs the agent out. Its next call is refused, and it has to sign in again to work. You can revoke an agent you signed in yourself; revoking someone else’s needs the Admin role.

An agent is also revoked when the person it acts as leaves the team or is removed from it. There is no key to rotate: a signed-in agent renews its own access, and one unused for 30 days has to sign in again.

Use it

curl https://api.deploybase.eu/api/v1/projects \
  -H "Authorization: Bearer $DEPLOYBASE_API_KEY"

API keys and dashboard sessions share the Authorization: Bearer header. The dbk_ prefix is what tells them apart.

The CLI reads the same variable, so setting it is all a CI job needs:

env:
  DEPLOYBASE_API_KEY: ${{ secrets.DEPLOYBASE_API_KEY }}

What a key can do

A key is scoped to your team and acts with Member permissions, whatever role the person who created it holds. That means it can:

• Create and update projects, trigger and cancel deployments, promote a deployment to production
• Read and write environment variables, create and revoke share links
• Read domains, team members, form submissions, build logs, function runs, and the plan and usage

And it cannot:

• Delete a project or a deployment (deleting a preview is fine)
• Add, verify or remove a domain
• Read invoices, change the plan, invite or remove members, or transfer ownership

This is deliberate. The destructive operations stay with a person who signed in. If a key leaks, the blast radius is a bad deploy, which you can roll back, not a deleted project, which you cannot.

There is no per-project scoping: a key reaches every project on its team.

Rate limits

100 requests per minute, per team, per endpoint. The bucket is keyed on the team and the request path together, so polling one deployment does not eat into your budget for creating another. The team half means a second key buys no extra throughput: every key and every signed-in session on the team share the same buckets.

A signed-in agent shares those buckets too, and has a lower limit of its own on top: 60 requests per minute per endpoint, so one busy agent cannot use up the whole team’s budget.

Every response carries your remaining budget, so a client never has to guess:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1789000000

X-RateLimit-Reset is a Unix timestamp. Over the limit you get 429. A polling loop is the usual cause. When you are waiting on a build, poll every five seconds rather than continuously, or use --wait in the CLI.

Rotate a key

Rotating gives a key a new secret and keeps the key itself: the same name and the same place in the list. On API keys, open the key’s actions menu (the three dots at the end of its row) and choose Rotate key, or use Rotate in the row of an agent key that is expiring or has expired. The new key is shown once; copy it and update everything that uses the old one.

The old secret stops working on the very next request. An agent key also gets a fresh 90 days, which is how you bring back one that has expired. A revoked key cannot be rotated: create a new one instead.

Over the REST API, rotation is one call with an empty body. It needs the Admin role, which an API key never has, so use a signed-in admin’s token as $DEPLOYBASE_TOKEN:

curl -X POST https://api.deploybase.eu/api/v1/api-keys/01234567-89ab-cdef-0123-456789abcdef/rotate \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The new secret is in data.raw_key of the response, and only there.

Rotate without a gap

One-click rotation kills the old secret at once, so anything still holding it fails until you update it. If a key is used in places you cannot all update at the same moment, swap it in this order instead:

1. Create a new key
2. Update the places that use the old one
3. Revoke the old key

Revocation also takes effect on the very next request, so doing it in that order means nothing is ever briefly unauthenticated. Reversing it means an outage of exactly as long as step 2 takes.

Rotate on a schedule that matches how the key is stored, and rotate immediately when someone with access to it leaves.

Keeping a key safe

A key is a bearer credential: whoever holds it is your team, at Member level.

• Never commit one. If you do, revoke it before you rewrite history. Rewriting history does not un-publish what was pushed
• Keep it in your CI provider’s secret store, not in a workflow file, an image or a .env you might deploy
• Use a separate key per system, so revoking one does not break the others. What each key did then tells you which system a request came from, and a key nothing uses any more stands out
• A key in your shell history is a key in a file. Prefer export DEPLOYBASE_API_KEY=$(pass deploybase) or your platform’s equivalent

Standard keys never expire on their own. That is convenient and it is also the argument for rotating them yourself.

Troubleshooting

A request fails with 401 and the code API_KEY_EXPIRED. The key is an agent key past its 90 days. Rotate it (see Rotate a key) and put the new secret wherever the old one was. Over MCP the same failure reads Authentication failed: the API key has expired.

A request fails with 401 and the code UNAUTHORIZED. The key is mistyped, incomplete or revoked. Check that the whole key, dbk_ included, made it into the header. A revoked key cannot come back; create a new one.