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 | niyra_ask: synchronous Q&A |
niyra:execute | niyra_execute: task execution, including running tools that take action (email, calendar, integrations) |
niyra:followup | Continuing existing conversation threads with conversation_id |
niyra:memories:read | niyra_memories: search the user's memory store |
niyra:memories:write | niyra_remember: add a new memory |
niyra:tasks:read | niyra_get_task: 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.
niyra:ask
Read + memory-aware
For apps that personalize based on what Niyra knows about the user but don't take action:
niyra:ask niyra:memories:read
Full agent integration
For apps that need Niyra to actually do things (send emails, file tickets, schedule meetings):
niyra:ask niyra:execute niyra:followup niyra:tasks:read
Memory-sync integration
For apps that ingest user data into Niyra (e.g. a CRM that wants Niyra to know about every customer):
niyra:memories:read niyra:memories:write
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:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "insufficient_scope",
"error_description": "this endpoint requires scope niyra:execute",
"scope": "niyra:execute"
}
The scope field on the response advertises the minimum scope the endpoint needs, useful for "we should re-run OAuth with broader consent" flows.