Authentication
Organization grants, API keys and session authentication.
A login alone does not enable the API. Box Observer provisions each organization’s datasets, country access and cinema-market boundary explicitly.
Get access
Ask your Box Observer administrator to enable API access for your organization. Specify the integration name, required datasets and credential lifetime. Provisioning is managed by Box Observer; there is no public key-creation or OAuth client-credentials endpoint.
The default operator grant covers its cinemas and competitors in markets where it has an active venue. National distributors and release calendars are limited to granted countries; the canonical film catalogue is shared reference data. A country-wide cinema grant requires explicit provisioning.
Server-to-server authentication
Use a scoped bo_live_ API key as a bearer token. The secret is delivered once; only its SHA-256 hash is stored. Keep it in your server’s secret manager, never in browser code, URLs, logs or source control. Keys expire, defaulting to 90 days and never extending beyond their organization grant.
curl --fail-with-body https://api.boxobserver.com/v1/account \
-H "Authorization: Bearer $BOX_OBSERVER_API_KEY"Check your effective access
GET /v1/account returns your authentication method, organization, key ID when applicable, effective scopes and configured limits. Its access.mode is operator_markets or countries. Query filters can narrow this grant; they cannot broaden it. Out-of-scope item reads return 404; collections omit those records.
| Scope | Permission |
|---|---|
catalog:read | Directories, film identities, distributors and release calendars. |
schedules:read | Showings and current prices; also requires catalog:read. |
availability:read | Seat observations embedded in showings; without it these are null and observed capacity is excluded. |
history:read | Archived/all lists and archived items require this in addition to the resource’s scopes. Availability observation history also requires schedules:read and availability:read. |
Rotate and revoke credentials
- Request a replacement key with the same or narrower scopes.
- Store it in your secret manager and verify
/v1/account. - Switch your integration to the replacement and revoke the old key.
Revocation and grant changes are checked on every authenticated request, without an entitlement cache. An in-flight request may finish. Revoking the organization grant blocks all its keys and sessions. A key can never expand the organization’s scopes.
Box Observer sessions and browsers
Box Observer Clerk session JWTs are also accepted. The session must identify an active organization, and the identity database must contain an active user, membership and API grant. Removed memberships are denied after the Clerk webhook updates the identity projection. A session without an active organization receives 403.
Browser requests are restricted to configured Box Observer origins. Server-to-server clients do not use browser CORS, but still require an authorized credential. These docs do not collect or submit your secrets.