Authentication & scopes

You generate an API token in your Devici workspace. The token gives you a clientId + secret pair — your credentials. Your AI client sends those credentials on every tool call, using HTTP Basic auth (Authorization: Basic base64(clientId:secret)) or the paste-friendly X-Devici-Client-Id + X-Devici-Client-Secret headers. The MCP enforces the token's scope on every action.

There's no browser sign-in dance, no separate OAuth client to register — you control your tokens directly from your Devici settings.

How tokens work

┌──────────────────────────────────────────────────────────────────┐
│  You sign in to Devici → create an API token with chosen scopes  │
│  Token has a name, scopes, and an optional description           │
└──────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│  You paste the credentials into your AI client; it sends them   │
│  as auth headers on every MCP tool call                         │
└──────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│  Devici MCP validates the token, looks up its scopes, and        │
│  enforces them per tool. Calls outside scope return 403.         │
└──────────────────────────────────────────────────────────────────┘

Generate a token

Sign in to your Devici workspace.

Open the API tokens page from the sidebar:

If you're an Admin: open My API Tokens.
If you're an Owner or Super Admin: open Security → Manage API Access.

(If you don't see either, your role doesn't have API token management — ask your workspace owner.) 3. Click Create API token. 4. Configure the token:

Field	Description
Name	A label that appears in audit logs (e.g. `Cursor — Anthony's MacBook`)
Scopes	What the token can do
IP Address allowlist	Optional. Restricts the token to a specific IP or CIDR. Leave empty for tokens used by MCP clients — see the warning below.

Click Create API token to submit. The token's clientId and secret appear once — copy both now. You won't see the secret again — Devici doesn't store it, so it can't be recovered. Lose it and you'll need to regenerate the token from the same page.

IP allowlists not supported through MCP (temporary)

If you set an IP allowlist on the token, all MCP calls will be rejected with 403 IP address not allowed. The MCP server reaches Devici from its own egress IP, not yours — so the allowlist sees the MCP server, not the client. For tokens used by MCP clients, leave the IP allowlist empty. We plan to pass the original caller's IP through; until then, no allowlist on MCP tokens.

You can have multiple active tokens at once — one per AI client, one per machine, one per pipeline. Different tokens can have different scopes.

Recommended pattern

One token per (client × machine). For a developer using Cursor on a laptop and Claude on a desktop, that's two tokens — easy to revoke if either machine is lost without affecting the other.

Encoding the Basic auth header

If your MCP client only accepts a single Authorization header (not the paste-friendly X-Devici-Client-Id / X-Devici-Client-Secret pair), you need to base64-encode clientId:secret first. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET below with the values from your API token.

macOS / Linux:

printf '%s' 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64

Windows (PowerShell):

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET'))

Use the resulting string as the header value:

Authorization: Basic <encoded-value>

Don't leave the secret in your shell history

These one-liners record the secret in your shell history. For ongoing use, store the secret in your password / secret manager and have your client read it from there.

Managing API tokens and scopes

Devici MCP uses scoped API tokens generated from your Devici workspace.

To learn how to:

Create API tokens
Configure scopes
Rotate or revoke tokens
Troubleshoot authentication issues

See the main platform documentation:

Managing API Tokens

Token lifecycle

Rotation

Best practice is to rotate tokens on a schedule (every 90 days is a reasonable default). Devici doesn't enforce rotation, but auditors usually do.

To rotate without downtime:

Generate a new token with the same scopes.
Update your AI client to use the new token.
Verify a tool call works.
Revoke the old token from the same page where you created it (My API Tokens for Admins, Security → Manage API Access for Owners/Super Admins).

Revoke

To revoke a token at any time:

Open the page where the token was created (My API Tokens for Admins, Security → Manage API Access for Owners/Super Admins).
Find the token in the list and click Revoke.

Revocation is immediate. The next request using that token returns 401 invalid_token.

If a machine is lost or compromised, revoke its token first; everything else can wait.

Tokens for CI / pipelines

For pipelines, scheduled jobs, or background services that call Devici MCP without a person in the loop, use a regular API token — there's no separate "service account" entity in Devici.

Create the token following the steps in Generate a token.
Give it only the scopes the pipeline needs.
Store the clientId and secret in your CI provider's secret manager (GitHub Actions secrets, GitLab CI variables, Vault, etc.). Never commit them to source.
In the pipeline, send them as auth headers on requests to https://mcp.devici.com — same as an AI client (either Authorization: Basic base64(clientId:secret) or the X-Devici-Client-Id / X-Devici-Client-Secret pair). No additional flow.

To make the token survive person changes, have a workspace Owner create it — token ownership stays with that user account, so don't tie pipeline credentials to an individual who might leave.

Common errors

Error	Meaning	Fix
`401 unauthorized`	Credentials missing, malformed, or rejected by Devici (wrong clientId/secret, disabled token, role not allowed for API access)	Verify the clientId + secret are correct and the token is still active in My API Tokens (or Security → Manage API Access for Owners/Super Admins)
`403 IP address not allowed`	The token has an IP allowlist set, but MCP traffic reaches Devici from the MCP server's egress IP, not yours	Remove the IP allowlist on this token, or use a separate no-allowlist token for MCP — see the note under Generate a token
`403 Insufficient scope: required <resource>:<permission>`	Token doesn't include the scope this tool requires	Generate a token with the required scope, or call a different tool