Scopes - Reintersect Developers

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.	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:

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:

{
  "_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.

​Scope list

​Declaring scopes

​At runtime

Scope list

Declaring scopes

At runtime