API Tokens for IDEs

The API key field in your editor takes a Verdictan application token, which these guides also call the client API token. It identifies the editor to your gateway. The provider key stays on the gateway.

Give each developer or workload its own token. You can then limit it, see which requests it made, and revoke it without affecting anyone else.

Three credentials

Credential	Held by	Sent to
Gateway runtime token	The verdictan gateway run process, from VERDICTAN_API_TOKEN	The Verdictan control plane
Client API token	The editor's model client or MCP client	The gateway, as Authorization: Bearer <client-api-token>
Provider credential	The gateway's provider target, from secret_key_ref	The upstream model provider

The gateway uses its runtime token for configuration, registration, telemetry, and relay connections. It never belongs in an editor.

Client tokens start with vdt_. Both the model endpoint and the MCP endpoint accept them as the Bearer token. The MCP endpoint answers 401 with missing_api_key when there is no Bearer token, and with invalid_api_key when the value does not start with vdt_. The Console lists client tokens on the API Tokens page as an Access Key or a Gateway Key; both come from one token system.

Before you start

• A gateway the editor can reach. See Gateway Setup for IDEs.
• The model base URL, the published MCP hostname, or both.
• Access to the Console API Tokens page.

Create a client API token

1. In the Console, open API Tokens.
2. Create one token per developer, team, or automated workload.
3. Give it only the permissions it needs, and set model limits, a budget, and an expiry.
4. Test the whole editor flow with one narrowly scoped token before you issue tokens to a team.

Store the token in the client

The token goes in the model client's API key field. For MCP clients, use the client's own secret mechanism:

Client	How to store the token
Codex CLI	--bearer-token-env-var with the variable name
VS Code	A password input variable in .vscode/mcp.json
Cursor and Windsurf	Environment variable interpolation in the MCP header
Continue	A git-ignored .env file, read with ${{ secrets.<NAME> }}
Clients with a protected settings screen	The client's documented secret store

• Never commit a raw token.
• Prefer the client's secret store or the OS keychain.
• A GUI app may not see variables from your interactive shell. Check that the app process can read the variable.
• If a token shows up in a log, screenshot, or commit, rotate it immediately.

Each client guide has the exact configuration. Gateway MCP Surface has the Codex CLI command and other MCP examples.

Verify

1. List models with the new token:

   export VERDICTAN_CLIENT_TOKEN="<client-api-token>"
   
   curl --fail http://127.0.0.1:41002/v1/models \
     -H "Authorization: Bearer ${VERDICTAN_CLIENT_TOKEN}"

2. Send the short model request. A model list alone does not prove the token may call a model, or that the provider key and budget work.

3. After you configure the editor, send one request from it. Then run verdictan events tail --since 10m and look for the matching event.

Rotate a token

1. Create a replacement with the same limits.
2. Switch one client to it, send one request, and check for its event with verdictan events tail --since 10m.
3. Switch the remaining clients.
4. Revoke the old token.

Note both token names during the rotation. To tell which token made a request, use events (verdictan events tail, or GET /v1/events with its required since parameter) together with the token metadata. History adds session context when capture is on, but it is not the place to match credentials.

Troubleshooting

Symptom	Cause	Fix
401 from the gateway	The Bearer value is missing, is not a vdt_ token, or belongs to an expired or revoked token	Check the raw value, the token's status and expiry, and the client process environment.
403 from the gateway	The token lacks a role, binding, model, provider, budget, or publication access it needs	Review each limit on the token in the Console.
A GUI client cannot find the token	The app did not inherit your shell environment	Start it from a shell that exports the variable, or use its keychain.
Events show an unexpected token	Two clients share a token, or a rotation is unfinished	Give each client its own token and finish the rotation.

For endpoint and event problems, see IDE Integration Troubleshooting.

Next steps

• Manage API Tokens: roles, expiry, and revocation in the Console.
• Gateway MCP Surface: connect an MCP client with the token.