> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens

> Personal and workspace tokens for the CLI, MCP, and direct API access.

Every programmatic access to Nora — CLI, MCP, direct API calls — uses a token. Two flavors.

## Two token types

| Type                   | Scope                                                     | Best for                           |
| ---------------------- | --------------------------------------------------------- | ---------------------------------- |
| **Personal API token** | Every workspace you belong to. Follows your role in each. | Interactive dev, personal CLI use. |
| **Workspace token**    | One workspace. Custom scope. Not tied to a user.          | CI/CD, integrations, MCP servers.  |

Both authenticate the same way (Bearer header). The difference is scope and lifecycle.

## Personal API tokens

**Settings → Security → API tokens → Personal → New token**.

Configure:

* **Name** — a human-readable label. "MacBook CLI", "Home Cursor".
* **Expiration** — optional. Never / 30 days / 90 days / 1 year.

The token is displayed once. Copy immediately; you cannot see it again.

Personal tokens act on any workspace you belong to. Your role in each workspace determines what the token can do.

When you leave a workspace, tokens continue to work on remaining workspaces. When you leave the account entirely, all tokens are revoked automatically.

## Workspace tokens

**Settings → Security → API tokens → Workspace → New token**.

Configure:

* **Name** — "GitHub Actions CI", "internal Slack bot", "Cursor for the on-call team".
* **Scope** — what the token can do:
  * **Read-only** — inspect Flows, Traces, but no writes.
  * **Read-write, no publish** — full editing, no shipping to production.
  * **Full** — everything the workspace's max-role member can do.
  * **Custom** — cherry-pick operations.
* **Expiration** — same options as personal.

Workspace tokens are the right pick for automation:

* Not tied to a person. If a team member leaves, the token keeps working.
* Narrower scope. A read-only token can't accidentally publish.
* Cleaner audit — the audit log shows "workspace token: GitHub Actions CI" rather than a personal name.

Prefer workspace tokens for anything longer-lived than a single dev session.

## Using a token

### With the CLI

```bash theme={null}
export NORA_TOKEN="your-token"
nora flows list
```

Or one-shot:

```bash theme={null}
NORA_TOKEN="your-token" nora flows list
```

### With MCP

Set `NORA_TOKEN` in the MCP server config. See [MCP setup](/settings/connections/mcp).

### With direct API

```bash theme={null}
curl -H "Authorization: Bearer $NORA_TOKEN" \
     https://api.platform.nora.my/v1/flows
```

## Rotating

Rotation is create-new + revoke-old:

1. Issue a new token in Settings.
2. Update the token in the consuming system (CI env, MCP config, etc.).
3. Verify the new token works.
4. Revoke the old token.

There's no "regenerate" operation — replacement is explicit so you know what's happening.

For CI:

```yaml theme={null}
env:
  NORA_TOKEN: ${{ secrets.NORA_TOKEN }}   # rotate this secret in GH → the token itself in Nora
```

## Revoking

**Settings → Security → API tokens → click a token → Revoke**.

Revoke is instant — the token is dead within seconds. Existing requests using it may complete or fail (short race window); new requests fail with 401.

Revoke immediately if:

* You suspect leak.
* A team member leaves (revoke their personal tokens).
* A CI job or service that owned the token is retired.

## Audit

Every token issue, use, and revoke is audited (see [Audit trail](/reliable/versions/audit)):

* Who issued the token, when, with what scope.
* Which token authenticated each API call (redacted; only the token ID, not the value).
* Every revoke, with actor.

If a token is compromised, the audit log shows exactly what actions the token took while active.

## Token expiration policies

Workspace policies (see [Access](/settings/workspace/access)) can enforce:

* **Max expiration** — no token may be issued with expiration beyond N days.
* **Required expiration** — no "never expires" tokens.
* **Rotation reminders** — tokens older than N days show a warning in the UI.

Recommended for regulated workloads: enforce 90-day max, plus rotation reminder at day 60.

## Personal vs. workspace decision tree

* Just me on my laptop, occasionally? → Personal.
* CI, a bot, an MCP server anyone on the team uses? → Workspace.
* One-off script I'm running today? → Personal is fine.
* Anything long-lived → Workspace.

## Related

* [`nora auth`](/cli/auth) — CLI-side auth.
* [MCP setup](/settings/connections/mcp) — using tokens with coding agents.
* [Access & policies](/settings/workspace/access) — role checks apply to tokens.
* [Audit trail](/reliable/versions/audit) — every token event is logged.