Scopes
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 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.
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.
When a scope is missing
The API answers 403 with the forbidden error code. The WWW-Authenticate response header names what to add:
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.
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.