Authentication & token model
The Viewcy API uses bearer-token authentication. Pass your token in the Authorization header on every request:
Authorization: Bearer YOUR_API_TOKEN
What a token represents
A token represents a Viewcy Profile — either a User or a School. The token has full rights over the resources its owner owns. When you call the API with a token, every read and write is scoped to what that owner can see and modify.
Where tokens come from
Tokens are minted in the Developer Zone of a Viewcy account. Both Users and Schools have a Developer Zone — open the account you want the token to act on behalf of and create the token there.
A token always acts as its owner. There is no impersonation or account-switching at the token level.
Acting on accounts you don't own
If you collaborate on another User or School (for example, a teacher invited to manage a course on a School account), your personal token does not reach into that other account. The collaboration grant lives inside the Viewcy UI and does not extend to API-token access.
To build an integration that operates on accounts other than your own — for example, a third-party app installed by many Schools — use OAuth 2.0. You register an application, the account owner authorizes it on a consent screen, and the resulting access token acts as that owner, limited to the scopes they granted.
Scopes
There are two kinds of token, and they treat scopes differently:
- Personal access tokens — minted in the Developer Zone. They carry the full rights of their owner and are not scope-limited, much like a GitHub personal access token. Every read and write the owner can perform is available.
- OAuth access tokens — issued to a third-party application. They are scoped: the application requests scopes, the owner grants them at authorization, and the token may only call endpoints its granted scopes cover. A request that needs a scope the token doesn't hold returns
403 Insufficient scope— distinct from the404returned for resources the owner doesn't own.
| Scope | Grants |
|---|---|
events_read | Read events, occurrences, recurring schedules, tickets, and locations |
events_write | Create, update, delete, publish, and unpublish events — and all nested occurrences, recurring schedules, and tickets |
upload_files | Create direct uploads (POST /uploads) |
orders_read | Read orders |
patrons_read | Read patrons |
revenue_read | Read revenue |
activities_read | Read the activity feed |
events_write is the single umbrella scope for every event mutation — there are no finer-grained write scopes (no separate "publish" or "delete" scope). Orders, patrons, and revenue are read-only.
Unauthorized access
When a token is missing or invalid, the API returns 401 Unauthorized.
When an OAuth token is valid but lacks a scope the endpoint requires, the API returns 403 Insufficient scope. Personal access tokens are never scope-limited, so they don't hit this.
When a token is valid but the requested resource is not owned by the token's owner (or doesn't exist), the API returns 404 Not Found. The API does not distinguish "doesn't exist" from "exists but isn't yours" — both look identical from the outside. Don't treat the absence of 403 as a bug; it's intentional.
See also
- Idempotency — use the
Idempotency-Keyheader to make retries of write requests safe. - Async, destructive, and idempotent operations — the rules every write endpoint follows.