> ## Documentation Index
> Fetch the complete documentation index at: https://developers.reintersect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Every scope an app can request, what it allows, and which client methods and events need it.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

A scope limits what an install can read or change through the Reintersect API. You never list
scopes on the app. Each piece declares the scopes its own handlers use, and subscribed events add the
read scopes they imply. The app's scopes are the union of these, and admins see the list on the
consent screen.

## Scope list

| Scope | Allows | Needed by |
| - | - | - |
| `conversations:read` | Hearing about posts, replies, mentions, links to your objects and the conversations Reintersect finds in chat, in circles the app can [reach](/concepts/install-and-consent#reach). | Message actions (added automatically), `post.created`, `reply.created`, `app.mentioned`, `reference.created`, `reference.removed`, `message.filed`, `conversation.updated`, `conversation.agreed` |
| `decisions:read` | Hearing about published and updated decisions. | `decision.published`, `decision.updated` |
| `calls:read` | Hearing about call recaps. | `call.recapReady` |
| `replies:write` | Posting messages and app stream events authored as the app. | `reintersect.replies.create`, `reintersect.streams.sendEvent`, `POST /v0/replies`, `POST /v0/streams/events` |
| `notifications:write` | Sending inbox and push notifications to members. | `reintersect.notifications.send`, `POST /v0/notifications`, `notify` in action results |
| `blocks:write` | Inserting blocks and changing their state outside an interaction. | `blocks.insert`, `update`, `replace`, `updateWhere` |
| `references:write` | Pushing reference fields and asking Reintersect to resolve one again. | `references.push`, `references.revalidate`, `PUT /v0/references` |
| `search:write` | Adding your app's objects to Reintersect search. | `PUT` and `DELETE /v0/search/objects` |
| `memories:write` | Saving workspace memories, credited to your app. | `POST /v0/memories` |
| `decisions:write` | Reserved. No endpoint uses it yet. | none |

For now, read scopes only control which events your app receives. Apps have no read endpoints.

Some things need no scope:

* Rendering your own blocks and running their actions when a member clicks.
* Resolving and searching your own references.
* Reading, querying and revalidating your own blocks.
* Updating the block an action runs on with its interaction token, within 15 minutes.
* The `app.installed`, `app.uninstalled`, `app.reconsentRequired`, `block.created` and
  `block.removed` events.

## Declaring scopes

Declare scopes on the piece whose code uses them:

```tsx theme={null}
import { defineEvent } from "@reintersect/sdk/app";
import { Paragraph } from "@reintersect/sdk/components";

export const OnDecision = defineEvent(
  "decision.published",
  { scopes: ["replies:write"] },
  async ({ decision, reintersect }) => {
    await reintersect.replies.create({
      conversationId: decision.conversationId,
      content: <Paragraph>Logged: {decision.title}</Paragraph>,
    });
  },
);
```

This piece contributes `replies:write` from its options and `decisions:read` from the event it
handles. Blocks contribute the scopes of their actions. Routes contribute none and may only use
scopes that other pieces declare.

Calling a method the piece's scopes don't cover is a type error: the method's type becomes
`RequiresScope<"blocks:write">`, which names the scope to add. An unknown scope name is also a type
error.

## At runtime

Reintersect checks scopes on every API request. A request without the scope fails with `403` and
`ReintersectAppScopeMissingError`:

```json theme={null}
{
  "_tag": "ReintersectAppScopeMissingError",
  "message": "This install has not granted the notifications:write scope.",
  "path": [],
  "scope": "notifications:write"
}
```

You normally see this only when an install is still on an older version that granted fewer scopes.
Installs keep the scopes their admin approved until the admin approves a version that asks for more.
See [Publishing new versions](/concepts/install-and-consent#publishing-new-versions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.