API tokens and OAuth

What it is

For anything that talks to Deplo without a browser, like an MCP agent.

Settings -> API tokens, under your account. A token is personal: it belongs to the person who created it, and nobody else can see, edit or revoke it - not a team admin, not an instance admin.

How it works

A token is a principal with its own capabilities, not an impersonation of the person who made it. You choose what it can do when you mint it, and you can change that afterwards without reissuing it.

Its effective power is the live intersection of two things:

what the token was granted   AND   what its owner can still do

Where it can act is decided by the team, per member, with two capabilities:

Both are read live on every request. Taking a capability away from somebody immediately blunts every token they own, in that team. Removing them from the team cuts those tokens off completely. There is no forgotten credential quietly holding powers its owner lost a year ago, and nobody has to hunt for it: the lever is the member, never the token.

Settings -> Members shows how many tokens and agents each member has reaching the team - a number, never the credentials.

The secret is shown once, at creation. Only its hash is stored.

Create one

Use one

Send it as a bearer token, and name the team you are acting in:

curl -s https://deplo.example.com/api/graphql \
  -H "Authorization: Bearer deplo_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-Deplo-Team: team_1a2b3c" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ apps { id name status } }"}'

A bearer request acts in one team. Without the header it lands in the first team the token reaches. The full surface is in the API reference.

Scope, and the rule that surprises people

Naming a project or an app drops every team-wide capability in that team.

That is deliberate. A token scoped to one app should not also be able to manage the team's members. A scope that silently kept team-level powers would be a scope in name only.

Need both? Mint two tokens.

Connected clients and OAuth

A web AI application (claude.ai, chatgpt.com) cannot be handed a pasted token, so Deplo acts as an OAuth authorization server for exactly this one purpose.

Approving on the consent screen mints an ordinary API token with the capabilities and scope you picked there. The access token the client holds is only a pointer at that row:

• It appears in Settings -> API tokens, marked as such.
• Revoking it there stops the client immediately, in every team.
• The OAuth scopes decide nothing. The token's capabilities do.

By default the connection reaches every team where you hold Connect AI agents and MCP is on. Narrow it on the consent screen if the client should only see part of that.

Expiry

api_tokens.expires_at is checked before the team is picked and before the membership is read, so one comparison covers GraphQL, MCP and the deploy hook at once.

Nothing sweeps an expired token away, on purpose: the list has to be able to tell you why a credential stopped working.

Tokens minted before expiry existed have none, and stay that way until you edit them.

If it does not work

• 401 - missing, revoked, or expired.
• 403 on one field - the token lacks that capability, or the scope excludes that resource.
• It worked yesterday - your capabilities changed (Use API tokens gone means the token no longer reaches that team), it expired, or the team turned on two-factor.

See also