Authentication - NMotion Platform

Credential matrix

Client	Credential	Notes
Web console	Clerk session JWT	Full product surface
CLI / scripts / SDK	`Authorization: Bearer nmp_…`	Effective access = user RBAC ∩ PAT scopes
Public catalog / version	None	`GET /api/v1/version`, `GET /api/v1/catalog/…`

A PAT cannot elevate the owning user’s org/project role.

Personal access tokens

Prefix: nmp_
Created in Settings → API tokens (Clerk session required)
Stored by nmp in the OS keyring when available, with a 0600 file fallback
Env override: NMP_API_TOKEN

Scopes

Write routes that accept PATs require explicit scopes (for example imports:write, exports:write). Routes that omit PAT scopes reject tokens entirely and stay Clerk-session only (invites, profile mutations, many web-internal writes). workspace:read is the default floor for authenticated read APIs when using a PAT.

Token lifecycle API

These operations are Clerk-session only (PATs receive 403):

GET/POST /api/v1/users/me/tokens
DELETE /api/v1/users/me/tokens/{token_id}

Example

export NMP_API_TOKEN=nmp_…
export NMP_BASE_URL=https://platform.neural-motion.org

curl -sS \
  -H "Authorization: Bearer $NMP_API_TOKEN" \
  "$NMP_BASE_URL/api/v1/users/me"

See ADR 0002 in the repository (docs/adr/0002-developer-api-cli-boundary.md) for the full stability boundary.

⌘I