Authentication
Authentication
API keys and OAuth connections are scoped to one school owner, allowed areas and locations.
Get a key
The school owner creates a key in Settings → Developers & Integrations → API Keys. Name the tool, choose access and locations, then copy the secret once. Live keys start with sk_live_; keys for marked, founder-provisioned DEV sandboxes start with sk_test_. Secrets are stored as hashes. Only Enterprise school owners can use this feature; staff cannot manage keys on the owner’s behalf.
Use your key
Send Authorization: Bearer sk_live_… on every REST request. Keep it on a server. Test keys work only against their provisioned DEV sandbox; production refuses them. OAuth access tokens can authenticate REST requests too; /mcp accepts agent OAuth tokens only.
Access per area
Dedicated Zapier, Make and n8n app keys manage only their own webhook subscriptions, with event-area and location checks. Booking Intake keys remain intake-only. Normal API keys and OAuth connections use scoped business routes.
The 14 areas are families, classes, lessons, attendance, payments, progress, waivers, team, messages, schedule, staff, settings, leads, reports. Each supports none, read or write access, except reports, which is read-only. Write includes reads. Payment writes remain subject to mandatory owner approval.
Read each operation's exact scope. For example, the legacy location resource uses classes:read, while the current staff tool uses staff:read. Family lookup can include the notes or other sections explicitly requested within the grant; there is no blanket promise that an authorized AI connection sees only names. Payment-card details stay outside these read projections. Missing access returns 403 insufficient_scope.
Pools
Location restrictions apply to every route. No selected locations means all current/future owner locations. Lists omit inaccessible records; direct reads normally return not_found. Writes outside scope return location_forbidden. Records without a provable permitted location are excluded for restricted connections.
Revoke and rotate
Revoke a key in the app. For rotation, create a replacement, update your server and revoke the old key. OAuth connections are checked against their current permissions and revocation state on each call; owner approval and write persistence recheck current grants, expiration, roster and locations. A prepared proposal can be refused after permissions narrow or source fields change.
Agent sign-in
Agents use Sign in with Swum. The server creates an authorization request; the app reads its id and displays the server’s client identity, scopes and exact redirect. The owner chooses locations and Read Only, Ask Me First or Can Act. Dynamic clients display as unverified until verified through a separate trusted process.
Identity boundaries and approvals
Supported charges, refunds, contractor payroll actions and guarded family/swimmer removals require owner approval. The selected operation's schema determines its supported billing and cancellation options; legacy resource examples can expose fewer choices than the current tool routes. Family broadcasts always require owner approval, including on Can Act.
Family payment-method management, bulk exports, owner bank-account setup and Swum administrator operations remain outside the owner connector. Personal family and instructor actions keep their native identity requirements. A connection cannot change its owner, exceed granted areas or locations, or approve its own pending proposal.