---
title: "Key concepts"
description: "Understand tokens, scopes, resource levels, and naming conventions."
lastModified: "2026-08-21"
---

## 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.