API Keys

Personal API keys let command-line tools and editor integrations call CoderFlow as you. They are different from AI provider API keys: AI provider keys let agents call Claude, Codex, Gemini, Bob, or Grok, while personal API keys authenticate you to the CoderFlow server.

Use personal API keys for:

• The CoderFlow CLI
• The VS Code extension
• Scripts that call CoderFlow HTTP endpoints

How API Keys Work

An API key is tied to one CoderFlow user account. Requests send the key as a Bearer token:

curl -H "Authorization: Bearer pc_your_key" \
  "$CODERFLOW_URL/auth/me"

The key does not carry its own permission scope. After the server validates the key, CoderFlow resolves permissions from the user's roles and access bindings, the same way it does for a browser session. If the user loses access to an environment, the API key loses that access too.

API keys are shown only when they are created. Existing keys can be listed by name, creation time, and last-used time, but the secret value is not returned again.

Create a Key with the CLI

For most users, coder login is the easiest way to create and store a key.

coder login

Enter your username and password. The server creates a key named CLI Access and the CLI stores it in the active profile or CLI configuration.

When SSO is enabled, use:

coder login --sso

The CLI displays a verification code, opens the browser when possible, and polls the server until the OIDC login is approved. On approval, the server creates an API key and the CLI stores it in the active profile.

There is no separate coder login --api-key flow in the current CLI. If an administrator or script gives you an existing key, add it to the active profile:

coder profile set apiKey pc_your_key

For one-off automation, you can also pass a key through the environment:

CODER_API_KEY=pc_your_key coder list

Use a Key in VS Code

The VS Code extension uses the same API-key authentication path as the CLI. Open the CoderFlow Profile Manager from the extension and choose one of these flows:

• Enter a server URL and username/password. The extension calls the CLI login endpoint, receives a generated API key, and stores it in the selected profile.
• Choose Sign in with SSO when OIDC is enabled. The extension opens the browser, waits for approval, and stores the returned API key.
• Paste an existing key into the profile when you already have one.

The extension also has a workspace setting named profoundCoder.apiKey. CLI profile configuration takes priority when both are present.

Create and Revoke Keys by API

The server exposes self-service API-key endpoints for the authenticated user:

Action	Endpoint	Notes
List your keys	GET /api-keys	Returns key IDs, names, creation time, and last-used time. Secret values are omitted.
Create a key	POST /api-keys	Body: { "name": "Script name" }. The secret key is returned once.
Delete a key	DELETE /api-keys/:id	Revokes one of your own keys immediately.

These endpoints require either a browser session or an existing API key. They do not let a user list or revoke another user's keys.

Rotate a Key

Rotate keys when a device is replaced, a secret may have leaked, or you want to retire old automation credentials.

1. Create a new key with coder login, coder login --sso, the VS Code Profile Manager, or POST /api-keys.
2. Update the CLI profile, VS Code profile, script secret, or CI variable that uses the old key.
3. Test the new key with coder list or GET /auth/me.
4. Delete the old key with DELETE /api-keys/:id.

Keys do not currently have an automatic expiration time. Revocation is explicit: delete the key or delete the user account it belongs to.

Security Practices

• Treat API keys like passwords. Store them in the CLI profile, VS Code profile, or a secret manager, not in source control.
• Use one key per device or automation workflow so rotation has a small blast radius.
• Prefer SSO login for humans when your server requires centralized identity. The SSO flow still produces an API key for non-browser requests.
• Review stale keys by last-used time and delete keys that are no longer needed.
• Keep the server data directory protected. Personal API keys are server-side credentials.

Troubleshooting

Invalid API key

The key was deleted, mistyped, or belongs to a deleted user. Re-run coder login, refresh the VS Code profile, or update the stored key.

Forbidden after authentication succeeds

The key is valid, but the user does not have the required permission. Ask an administrator to review the user's teams and access bindings. See Permissions.

Confusing personal keys with AI provider keys

Personal API keys authenticate you to CoderFlow. AI provider keys are configured under provider authentication settings and are injected into task containers so agents can call model providers.