---
sidebar_position: 10
sidebar_label: API Keys
---
# 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:

```bash
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.

```bash
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:

```bash
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:

```bash
coder profile set apiKey pc_your_key
```

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

```bash
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](/admin/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.
