Skip to main content

Authenticate IDE Integrations with API Tokens

An IDE workflow can involve three credentials. They have different owners and uses. Do not reuse them interchangeably.

CredentialUsed bySent to
Gateway runtime tokenverdictan gateway runVerdictan control plane
Client API tokenIDE model client or MCP clientVerdictan gateway
Provider credentialGateway provider targetUpstream model provider

The shared Verdictan API token system supplies Access Keys and Gateway Keys as filtered views. Manage them on the console's API Tokens page.

Before you configure a client​

Have these values available:

  • the specified model base URL or published MCP hostname that you plan to use
  • a client token that has the correct role, expiry, model restrictions, and budget for that workload
  • the gateway runtime and provider credentials on the machine that runs verdictan gateway run. These credentials must be different.

Before you issue tokens to a team, start with one narrowly scoped client token. Then verify the client flow.

Gateway runtime token​

The gateway process reads its runtime credential from VERDICTAN_API_TOKEN. It uses that identity for configuration, registration, telemetry, and relay connectivity. Do not copy it into an IDE.

Model-client token​

Create a different token for each developer, team, or automated IDE workload. Use the narrowest roles, model restrictions, budgets, and expiry that fit the workflow. The client sends the token as:

Authorization: Bearer <client-api-token>

When the base URL points at the gateway, put the Verdictan client token in the client's API key field. Provider keys belong in the gateway's secret_key_ref, not in that client field.

MCP-client token​

The hosted /mcp route also must use a Verdictan API token. Store it through the MCP client's supported secret mechanism:

  • Codex: --bearer-token-env-var
  • VS Code: a password input variable in mcp.json
  • Cursor and Windsurf: environment interpolation in the MCP header
  • clients with a protected settings UI: the operating-system keychain

For example, Codex can reference the token without copying its value into the client configuration:

export VERDICTAN_MCP_TOKEN="<mcp-client-token>"
codex mcp add verdictan \
  --url "https://<published-hostname>/mcp" \
  --bearer-token-env-var VERDICTAN_MCP_TOKEN

The optional repository installer can write Cursor, VS Code, and OpenCode project configuration. It replaces the target files. Run it first with --dry-run, and review existing files:

export VERDICTAN_MCP_TOKEN="<mcp-client-token>"
./docker/install-mcp.sh \
  --dry-run \
  --hostname "<published-hostname>" \
  --token-env VERDICTAN_MCP_TOKEN

Safe storage​

  • Do not commit a raw token to source control.
  • Prefer the client's secret store or OS keychain.
  • If a GUI client reads an environment variable, make sure that the GUI process can read it. Availability in an interactive shell is not sufficient.
  • If logs, screenshots, or a committed file contain a token, rotate it immediately.

Rotation​

  1. Create the replacement token with the specified restrictions.
  2. Update one client.
  3. Verify the IDE flow.
  4. Update the remaining clients.
  5. Revoke the previous token.

Record the previous and replacement token names during rotation. Use request Events and token metadata to find which credential generated each decision. Query Events with verdictan events or GET /v1/events with the mandatory since. When History capture is enabled, History adds the retained session context. History is not the universal source for credential correlation.

Troubleshooting​

For 401, verify the raw bearer value, token status, expiry, and the client process's environment. For 403, examine role, binding, model, provider, budget, and publication restrictions. See IDE Integration Troubleshooting for endpoint checks.

Next steps​