# MCP API keys (/docs/mcp/api-keys)



An MCP API key gives an AI client access to selected Pollaris workspaces. Treat it like a password. The complete key is shown only when it is created or rotated; Pollaris stores a protected digest and cannot display the secret again.

## Choose scopes [#choose-scopes]

| Scope                     | Allows                                                                    | Workspace role required |
| ------------------------- | ------------------------------------------------------------------------- | ----------------------- |
| `pollaris.forms.read`     | List workspaces/forms, read drafts, compile DSL, and validate definitions | Viewer or higher        |
| `pollaris.forms.write`    | Create forms and replace drafts; also includes read access                | Editor or higher        |
| `pollaris.forms.generate` | Request AI-generated form previews; also includes read access             | Editor or higher        |

Use least privilege. A key used only for review should have `pollaris.forms.read`. Add `write` only when you want the assistant to save drafts, and add `generate` only when it should use Pollaris's configured AI generation service.

A key is also restricted to an explicit workspace list. Pollaris checks your current membership on every call, so removing a user from a workspace removes the key's access to that workspace too.

## Create a key in Pollaris [#create-a-key-in-pollaris]

Use the MCP API-key screen in your Pollaris deployment, if available:

1. Sign in again if prompted. Creating a key requires a verified email and a login from the last 15 minutes.
2. Give the key a recognizable name, such as `Cursor on work laptop`.
3. Select one or more workspaces.
4. Select the smallest set of scopes needed.
5. Choose an expiry. Deployments default to 30 days and can enforce a maximum; this repository's default maximum is 90 days.
6. Create the key and copy the complete `plr_mcp_v1_...` value immediately.

If your deployment does not yet provide the screen, an authenticated client can call the REST endpoint:

```bash
curl --request POST "https://api.pollaris.cc/v1/mcp/api-keys" \
  --header "Authorization: Bearer POLLARIS_USER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Cursor on work laptop",
    "workspace_ids": ["WORKSPACE_UUID"],
    "scopes": ["pollaris.forms.read", "pollaris.forms.write"],
    "expires_in_days": 30
  }'
```

The response contains `api_key` once and non-secret metadata under `metadata`. `POLLARIS_USER_TOKEN` is a recent Pollaris login token, not the MCP key.

## Store the key safely [#store-the-key-safely]

* Prefer a client-supported environment-variable or secret-storage option.
* If a client requires a literal key in a config file, use a user-level file, restrict its file permissions, and never commit it.
* Never paste a key into a chat message, issue, screenshot, form draft, URL, or browser bundle.
* Use a separate key for each device or client. This makes revocation and audit history useful.

macOS/Linux example:

```bash
export POLLARIS_MCP_API_KEY='plr_mcp_v1_REPLACE_ME'
```

Set the environment variable in the shell or launcher that starts the MCP client. Adding it to one terminal does not automatically make it available to an already-running desktop application.

## List keys [#list-keys]

```bash
curl "https://api.pollaris.cc/v1/mcp/api-keys" \
  --header "Authorization: Bearer POLLARIS_USER_TOKEN"
```

The list returns names, key hints, scopes, workspace IDs, expiry, last use, creation time, and revocation time. It never returns raw keys.

## Rotate a key [#rotate-a-key]

Rotation revokes the old key atomically and creates a replacement with the same name, workspaces, scopes, and remaining lifetime (subject to deployment limits).

```bash
curl --request POST "https://api.pollaris.cc/v1/mcp/api-keys/KEY_UUID/rotate" \
  --header "Authorization: Bearer POLLARIS_USER_TOKEN"
```

Copy the returned `api_key`, update the client, restart/reload the connection, and confirm `list_workspaces` works. The old value stops working immediately.

## Revoke a key [#revoke-a-key]

```bash
curl --request DELETE "https://api.pollaris.cc/v1/mcp/api-keys/KEY_UUID" \
  --header "Authorization: Bearer POLLARIS_USER_TOKEN"
```

Revocation is immediate and cannot be undone. Create a new key if access is needed again.

## If a key is exposed [#if-a-key-is-exposed]

1. Revoke it immediately.
2. Create a replacement with the minimum scopes and workspaces.
3. Update only the intended client.
4. Review the key's `last_used_at` value and relevant workspace activity.