---
title: Scopes
description: Every service-token and agent scope, what it allows, who may grant it, and how conditional scope rules change what a request needs.
---

A scope is one permission a credential holds. Service tokens and agent connections carry a list of scopes, and every operation declares the scopes it needs. A request succeeds only when the credential holds all of them.

## How scopes work

- **Additive.** A credential has exactly the scopes it was granted. There is no wildcard and no platform-wide scope.
- **Reads and writes are separate.** A write scope never implies its matching read scope. A token that can create programs cannot list them unless it also holds `catalog.read`.
- **Fixed at creation.** A token's scopes cannot be edited. Rotating a token keeps the same scopes. To change access, create a new token.
- **Bounded by the person who grants them.** A credential is never broader than the owner or admin who created it. Each scope below has a lowest role that may grant it. Admins cannot grant owner-only scopes, and staff cannot create credentials at all.
- **One school.** Scopes apply inside the school the credential belongs to.

Scopes marked **Sensitive** reach student, guardian, payment, or access-control data. The grant screen labels them so the choice is deliberate, and a request that needs a sensitive read scope is written to the school's audit log.

## Find the scopes an operation needs

Every operation in the [API reference](/api) and in the OpenAPI contract lists its scopes in an `x-required-scopes` extension. For example, listing programs needs `catalog.read`, and creating an enrollment needs `enrollments.write`.

Job reads need two grants: `organization.read` plus the scope of the operation that created the job. See [Async operations](/developers/async-operations).

## Conditional scopes

Some commands need extra scopes depending on what you put in the request. The contract lists them under `x-scope-rules`, and Soljio enforces them at run time, including when it replays a saved result for a retried request.

| Condition | Extra scope applies when |
| --- | --- |
| `always` | Every request to the operation |
| `published_status` | `status` is supplied and is not `draft` |
| `status_change` | `status` is supplied, including `draft` |
| `term_assignment` | `term_id` is supplied |
| `new_program` | `new_program_name` is supplied without `program_id` |
| `schedule` | Initial recurring schedule rules or explicit schedule sessions are supplied |
| `participant_consent` | A consent status, provider visibility, or link status is supplied |

For example, `create_offering` needs `catalog.write`, plus `catalog.publish` when it creates a published session or a new program in the same request, plus `schedule.apply` when it includes a schedule.

Schedule previews replace `schedule.apply` with `schedule.preview`. Every other scope the command needs still applies. See [Previews and approvals](/developers/previews-and-approvals).

## When a scope is missing

The API answers `403` with the `forbidden` error code. The `WWW-Authenticate` response header names what to add:

```http
HTTP/2 403
www-authenticate: Bearer error="insufficient_scope", scope="catalog.write"
```

When several scopes are missing, the `scope` value lists them separated by spaces. Because tokens cannot be edited, the fix is a new token. Agents are different: the person approving an agent chooses its access during approval, and changing it means connecting the agent again. See [Connect an agent](/developers/connect-an-agent).

## Scope reference

There are 53 scopes. The groups match the **Access** section of the **Create token** sheet. The **Dashboard label** column is the text shown beside each checkbox.

### Organization

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `domains.read` | Read custom domains | Read custom domains within this organization. | Owner only | No |
| `domains.write` | Manage custom domains | Manage custom domains within this organization. | Owner only | No |
| `instructors.read` | Read instructors | Read instructors, their status, and the school accounts they teach as. | Admin or owner | No |
| `instructors.write` | Manage instructors | Add instructors, update their details, and set their status. | Admin or owner | No |
| `locations.read` | Read locations | Read locations used by the catalog and schedule. | Admin or owner | No |
| `locations.write` | Manage locations | Manage locations within this organization. | Admin or owner | No |
| `organization.read` | Read organization profile | Read the organization profile and operating defaults. | Admin or owner | No |
| `resources.read` | Read resources | Read resources within this organization. | Admin or owner | No |
| `resources.write` | Manage resources | Manage resources within this organization. | Admin or owner | No |

### Programs and offerings

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `catalog.publish` | Publish offerings | Publish or unpublish an offering. | Admin or owner | No |
| `catalog.read` | Read programs and offerings | Read programs, offerings, and their schedule summaries. | Admin or owner | No |
| `catalog.write` | Manage programs and offerings | Create and update programs and draft offerings. | Admin or owner | No |

### Schedule

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `schedule.apply` | Apply schedule changes | Apply an approved schedule preview. | Admin or owner | Yes |
| `schedule.preview` | Preview schedule changes | Preview schedule changes without writing them. | Admin or owner | No |
| `schedule.read` | Read schedule | Read schedule rules and sessions. | Admin or owner | No |

### Participants

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `participants.consent.write` | Update participant consent | Update a participant's provider consent and visibility settings. | Owner only | Yes |
| `participants.details.read` | Read participant details and contacts | Read participant details and contacts within this organization. | Owner only | Yes |
| `participants.read` | Read participants | Read participant names and status. Contact details, birth dates, and notes stay private. | Admin or owner | Yes |
| `participants.write` | Manage participant profiles | Manage participant profiles within this organization. | Owner only | Yes |

### Enrollment and attendance

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `attendance.write` | Mark attendance | Mark attendance for a session roster. | Admin or owner | No |
| `enrollments.override` | Override enrollment outcomes | Force enrollment status, transfer an enrollment, or promote from the waitlist. | Owner only | Yes |
| `enrollments.read` | Read enrollments | Read enrollment records and their lifecycle status. | Admin or owner | No |
| `enrollments.write` | Manage enrollments | Create and cancel ordinary enrollments. | Admin or owner | No |
| `makeups.write` | Manage makeup credits | Manage makeup credits within this organization. | Admin or owner | Yes |
| `private_lessons.read` | Read private lessons | Read private lesson bookings, setup, availability and packs, including students and family contacts. | Admin or owner | Yes |
| `private_lessons.write` | Manage private lessons | Set up private lessons and book, approve, move, cancel and take attendance for them. | Admin or owner | No |
| `roster.contacts.read` | Read roster contacts | Read guardian contact hints on a roster for emergency and operational use. | Owner only | Yes |
| `roster.read` | Read rosters | Read session rosters without guardian contact details. | Admin or owner | Yes |

### Progress

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `progress.guardian_publish` | Publish progress to families | Mark skills on report cards that families can see. | Owner only | Yes |
| `progress.read` | Read progress | Read skills checklists and the marks on each student's. | Admin or owner | Yes |
| `progress.templates.write` | Manage report-card templates | Manage report-card templates within this organization. | Admin or owner | No |
| `progress.write` | Record progress | Mark skills on student checklists. | Admin or owner | No |

### Communications

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `communications.messages.read` | Read conversation messages | Read conversation contents and sender details. | Owner only | Yes |
| `communications.read` | Read communication status | Read delivery status counts for notifications. Message bodies and recipient addresses stay private. | Admin or owner | No |
| `communications.write` | Manage conversations and delivery settings | Manage conversations and delivery settings within this organization. | Owner only | Yes |

### Administration

| Scope | Dashboard label | Allows | Grant by | Sensitive |
| --- | --- | --- | --- | --- |
| `audit.read` | Read audit history | Read the organization's audit history. | Owner only | Yes |
| `exports.read` | Export organization data | Export organization data within this organization. | Owner only | Yes |
| `imports.write` | Preview and apply organization imports | Preview and apply organization imports within this organization. | Owner only | Yes |
| `invoices.read` | Read invoices | Read invoices within this organization. | Owner only | Yes |
| `invoices.write` | Manage invoices | Manage invoices within this organization. | Owner only | Yes |
| `operations.read` | Read operations queue and search | Read operations queue and search within this organization. | Admin or owner | Yes |
| `operations.write` | Manage operations queue | Manage operations queue within this organization. | Admin or owner | Yes |
| `payments.read` | Read payment records | Read payment records within this organization. | Owner only | Yes |
| `payments.refund` | Record refunds | Record refunds within this organization. | Owner only | Yes |
| `payments.write` | Record and reconcile payments | Record and reconcile payments within this organization. | Owner only | Yes |
| `private_lessons.payments` | Record private lesson payments | Record private lesson payments, refunds and pack sales, and send card refunds. | Owner only | Yes |
| `reports.read` | Read organization reports | Read organization reports within this organization. | Admin or owner | Yes |
| `reports.write` | Prepare organization reports | Prepare organization reports within this organization. | Admin or owner | Yes |
| `settings.read` | Read settings | Read operating settings. Invitation tokens and connected-account secrets stay private. | Admin or owner | No |
| `settings.write` | Update settings | Update schedule and notification defaults. | Owner only | Yes |
| `staff.invite` | Invite staff | Invite staff to admin and staff roles. | Owner only | Yes |
| `staff.read` | Read staff and invitations | Read staff and invitations within this organization. | Owner only | Yes |
| `staff.write` | Manage non-owner staff access | Manage non-owner staff access within this organization. | Owner only | Yes |

## Messages sent to families

There is no scope for sending an arbitrary message. Commands that change a school's data send the notifications the dashboard would send for the same change, and no extra grant is needed for that. The contract says, for example, that `cancel_enrollment` may promote a waitlisted student and send notifications, that `add_term_holiday` cancels the term's class dates on that day and notifies their families, and that the private lesson booking commands notify the family. `invite_staff` queues an email to the invitee.

Treat commands like these as ones that can reach families, and try them against a school you control first. Agents are asked to confirm with a person before calling them. See [Agents and MCP](/developers/agents-and-mcp).
