Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Was this page helpful?