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

​
Two token types

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

Or one-shot:

​
With MCP

Set NORA_TOKEN in the MCP server config. See MCP setup.

​
With direct API

​
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:

​
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):
  • 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) 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.