---
title: Scope catalog — what each OAuth / PAT scope grants
description: Complete list of Niyra API scopes, what each one allows, and how to pick the minimum set for your integration.
url: /docs/api-scopes
lastUpdated: 2026-06-11
---

# 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` | `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.

```text
niyra:ask
```

### Read + memory-aware

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

```text
niyra:ask niyra:memories:read
```

### Full agent integration

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

```text
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):

```text
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
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.

## Related

- [OAuth 2.1 flow + DCR](/docs/api-oauth)
- [Tool reference: niyra_ask](/docs/api-tool-niyra-ask)
- [Tool reference: niyra_execute](/docs/api-tool-niyra-execute)