Key concepts
Understand tokens, scopes, resource levels, and naming conventions.
Token
A Core API token belongs to one Brella organization. Send it in the Brella-API-Access-Token header. Treat the token like a password: store it in a secret manager, never place it in browser code, logs, tickets, or source control, and rotate it if it may have been exposed.
Scope
A token contains one or more scopes. Each scope grants access to one primary resource, such as Registrant, Sponsor, or EventAnalytics. A scope controls:
- whether it is enabled;
- whether the token can read and/or write;
- which events it covers;
- which fields are returned;
- which query filters callers may use;
- which rows are always hidden or allowed;
- which associations can be included;
- which write actions and request fields are allowed; and
- which fields are returned after a write.
A token can have at most one scope for a given resource. Use another token if a partner needs a materially different policy for the same resource.
Resource level
Every resource is either organization-level or event-level.
| Level | Collection URL |
|---|---|
| Organization | /api/core/organizations/{organization_id}/{resource} |
| Event | /api/core/organizations/{organization_id}/events/{event_id}/{resource} |
Using the wrong URL shape returns 400 Bad Request. An event-level resource requires the event ID; an organization-level resource rejects an event ID in the URL.
Naming conventions
Brella uses two naming styles intentionally:
| Context | Style | Example |
|---|---|---|
| Query parameters, request bodies, and scope settings | snake_case |
created_from, first_name |
| JSON:API response attributes and relationships | kebab-case |
created-at, first-name |
id is always returned as a JSON:API string and does not need to be selected in the scope.