Authentication and permissions
Beta — this API is in beta. Access is switched on per organization by Stello.
Send the secret on every request:
Authorization: Bearer YOUR_SECRET_KEYThe API accepts server-to-server requests. Secrets do not belong in client bundles, browser storage, URLs, analytics or application logs. A webhook signing secret is a separate credential and cannot authenticate API requests.
Up to 20 unrevoked keys can exist per organization. Selected-event access supports up to 500 event IDs per key. The dashboard retains a view of the 80 most recently revoked keys.
Organization access
Stello staff enables API access individually. An organization admin manages keys only for their own organization. Key access remains organization-owned when its creator leaves the organization. Admins should review and revoke keys when ownership of an integration changes.
Disabling organization API access blocks every key. A read the edge already holds can be served for up to 30 seconds longer (see caching and freshness); ticket checks are never held, so they apply at once. Re-enabling access restores otherwise valid keys; individually revoked keys remain revoked.
Event access
Every first-release key has the events:read permission. The dashboard offers:
| Setting | Accessible records |
|---|---|
| Events: all events | All of the organization’s events, including events created later |
| Events: selected events | Only the explicitly selected event IDs |
| Include sub-organizations | Also permits events from active direct sub-organizations with staff-enabled API access |
| Ticket lookup | Off by default. Lets the key call the ticket endpoint. Keys made before this option existed keep it off |
An empty selected-event set grants access to no events. It never means all events. Selection uses IDs, so renaming an event or changing its slug does not change access.
Both modes allow retrieval of permitted events in supported statuses. Archived events are excluded. Query parameters cannot bypass organization or event restrictions. Selected-event keys do not gain access to new events automatically.
Parent organizations
Enable Include sub-organizations separately on each parent key that needs this access. It is off for new and existing keys by default. Stello must also enable API access on each sub-organization.
The same three endpoints cover the parent and its eligible direct sub-organizations. List results are merged into one paginated sequence ordered by event start. Each event retains its owning org_id.
With all-event access, newly created events and newly eligible sub-organizations are included automatically. With selected-event access, only the chosen IDs are allowed. Changing the sub-organization setting in the dashboard clears the form’s event selection so you can choose from the updated scope before saving.
Removing the key permission, disabling a sub-organization’s API access, suspending or archiving the sub-organization, or removing its parent link removes access on subsequent requests. This also applies when following an older cursor. A sub-organization’s own key covers its own events.
Validity and revocation
Admins can name keys, change activation and expiration dates, change their event access, and revoke them. Secret values cannot be retrieved later. Create a replacement key if a secret is lost or needs rotation.
- A key is usable at its activation timestamp and later.
- A key is unusable at its expiration timestamp and later.
- An expiration date must be after the activation date.
- No expiration is allowed after the dashboard displays a warning to periodically review and rotate the key.
- An update to validity or permissions applies to the next request, including requests carrying an older pagination cursor.
- Revocation is permanent. Create a new key instead of undoing revocation.
The dashboard collects dates with an explicit timezone and displays the resulting instant. API timestamps use UTC.
Missing, invalid, inactive, expired or revoked credentials return 401. A valid key whose organization has API access disabled, or which lacks the required resource permission, returns 403. An event outside the key’s permitted organizations or selected-event set returns 404, like a nonexistent event.
The public API does not expose key-management endpoints. Key management uses the authenticated organization dashboard.