Scope catalog — what each OAuth / PAT scope grants

Scope catalog

Every token Niyra issues — OAuth access tokens minted via DCR, and Personal Access Tokens minted from Settings → API — carries an explicit scope set. Endpoints check scopes per call.

Available scopes

| Scope | Grants |
| ----- | ------ |
| niyra:ask | niyraask — synchronous Q&A |
| niyra:execute | niyraexecute — task execution, including running tools that take action (email, calendar, integrations) |
| niyra:followup | Continuing existing conversation threads with conversationid |
| niyra:memories:read | niyramemories — search the user's memory store |
| niyra:memories:write | niyraremember — add a new memory |
| niyra:tasks:read | niyragettask — poll status of background tasks |

Picking scopes

Read-only integration

If your app only asks questions, ask for niyra:ask and nothing else. The smallest possible blast radius if the token leaks.

Read + memory-aware

For apps that personalize based on what Niyra knows about the user but don't take action:

Full agent integration

For apps that need Niyra to actually do things — send emails, file tickets, schedule meetings:

Memory-sync integration

For apps that ingest user data into Niyra (e.g. a CRM that wants Niyra to know about every customer):

What scopes do NOT grant

- Scopes never grant access to billing, plan info, or account settings — those live on the Clerk-authed dashboard surface and are out of scope for the public API.
- Scopes do not grant access to the user's raw provider credentials (Gmail tokens, Calendar tokens, etc.). Niyra uses those internally; your token only sees the results of tool calls.
- Scopes do not grant cross-user access. Every token resolves to exactly one Niyra user.

Scope errors

When a request lacks a required scope, you get:

The scope field on the response advertises the minimum scope the endpoint needs — useful for "we should re-run OAuth with broader consent" flows.

Related

- OAuth 2.1 flow + DCR
- Tool reference: niyraask
- Tool reference: niyra_execute