Organization tokens let a partner, an agency or your own developers read or change your Brella data through the Brella Core API. Each token belongs to the organization, and its scopes decide which data, events, fields and actions it can use.

Before you start

You need to be an organization admin of the organization. Event admins don't see the API page.
Brella turns on API access for each organization. If API is missing from the organization sidebar, ask your Brella contact to turn it on.
Decide what the integration needs, for example "read the leads of 2 events" or "create and update sponsors". You grant each resource in its own scope.

Organization tokens and the personal API key

An organization token works only with the Core API. A personal API key works only with the Integration API, which the Brella app on Zapier uses. Each API refuses the other key.

Owner: an organization token belongs to the organization, and every organization admin can manage it. A personal key belongs to the admin who created it.
Access: an organization token can use only what its scopes allow. A personal key can use every event of every organization where its owner is an organization admin.
Number: an organization can have many tokens, for example one per partner. Each admin has one personal key.
Expiry: an organization token can have an expiry date. A personal key never expires.
Replacement: you rotate an organization token to get a new value. You replace a personal key by deleting it and creating a new one.

For the personal key, see Get your Brella API key and event ID.

Where to find it

Open Organizations, select Launch on your organization, then select API in the organization sidebar. The page opens on the Organization tokens tab.

API page on the Organization tokens tab, with the info message, the Create token button and the token list

How scopes work

A token has no access until you add a scope. Each scope covers one resource, such as Registrant, Sponsor, Lead or ContentSession, and sets:

Permissions: Read, Write or both.
Event access: All events, or Specific events that you select. All events includes events you create later. Specific events covers only the events you selected.
Readable fields: the fields the API returns. id is always returned.
Query fields: the fields the partner can filter on.
Row restrictions (some resources only): limits the partner can't change, for example only the leads of certain sponsors.
Write actions, Writable fields and Response fields: what the partner can create, update or delete, which fields they can set, and which fields Brella returns after a change. These appear only when the scope grants Write.
Included associations (some resources only): related records the partner can request with each record.

A token can have one scope per resource. For a second set of rules on the same resource, create another token.

Create a token

Open API > Organization tokens.
Select Create token.
Enter a Name of up to 100 characters, for example "Data warehouse export".
Optional: enter a Description of up to 255 characters.
Optional: choose an Expires date. Leave it empty for a token that never expires. Give partner tokens an expiry date, so a leaked token stops working on that date.
Select Create.
In Store your token, select Copy to clipboard and store the token in a password manager.
Select Close. The token's page opens.

Create token dialog with Name, Description and Expires filled in

Brella shows the token value only once. After you close the dialog, nobody can see it again. If the value is lost, rotate the token.

Add a scope

On the token's page, select Add scope.
Enter a Name. Leave Enabled on.
Choose the Primary resource. Reporting resources are listed under Analytics. You can't change the resource later.
Under Permissions, select Read, Write or both. For read-only resources, Write is unavailable.
Under Event access, choose All events, or choose Specific events and select the Events.
Under Read configuration, choose the Readable fields and the Query fields. If the form shows Row restrictions, add the restrictions you need.
If you selected Write, choose at least one of the Write actions, then the Writable fields and the Response fields. If you allow Create, the form names the writable fields that creating a record requires.
If the form shows Included associations, choose the related records the partner can request.
Select Add scope.
Repeat for each resource the integration needs.

Add scope drawer with Primary resource chosen, Permissions, Event access and Read configuration visible

Example: let a partner read one event’s attendee names

Suppose a reporting partner needs names and email addresses for people who joined Autumn Forum. Use your own event in place of this example.

Add a scope named Autumn Forum attendee report.
Choose Registrant as the Primary resource.
Select Read only under Permissions.
Choose Specific events and select Autumn Forum.
Under Readable fields, select first-name, last-name and email.
Under Query fields, select status.
Select Add scope and check that the saved scope is enabled for the chosen event with Read access.

Your developer can filter on status to request people who joined. The response contains id, names and email addresses. Granting a query field does not make it a returned field.

This scope permits filtering by status; it does not force the partner to use a filter. Tell the partner to request joined records for this report.

Example: allow a developer to create scan questions

Use a separate ScanningQuestion scope for the intended event. Select Write, then Create under Write actions.

Grant sponsor-id, title and field-type under Writable fields. Add options if the question offers choices, and title under Response fields.

The form requires sponsor-id when granting Create. The developer supplies an existing sponsor ID from that event and a valid question type. Write alone does not allow creation.

Write configuration with Create selected, writable title, field-type and sponsor-id fields, title as a response field, and Cancel and Add scope

Ask the developer to create one test question, then check the sponsor’s Lead Scans > Scan questions tab. Use the API reference for request values and validation rules.

Manage tokens and scopes

The token list shows each token's Expires date (Never if it has none), its Created date and its Status: Active or Expired. Select a token to open its page.

Rotate token: select Rotate token, then Rotate. The old value stops working at once, and the token keeps its scopes. Copy the new value from Store your new token and update the integration.
Delete a token: select Delete, then Delete again to confirm. The token and its scopes are removed, and integrations that use it lose access. This can't be undone.
Change a scope: select Edit next to the scope, make your changes and select Save. To pause a scope without deleting it, turn off Enabled.
Delete a scope: select Delete next to the scope, then Yes, delete.

Share the token with your developer

Send your developer:

The token value, through a password manager.
Your organization ID: the number after /dashboard/organizations/ in the admin panel address. See Get your Brella API key and event ID.
The resources, events and fields you granted.

Your developer sends the token in the Brella-API-Access-Token header of each request. Core API addresses start with https://api.brella.io/api/core/organizations/<organization ID>/. Resources that belong to an event add the event: https://api.brella.io/api/core/organizations/<organization ID>/events/<event ID>/sponsors. Ask the developer to handle pagination so the report includes every matching record.

Use the Core API reference for authentication, request examples and field values. Give the developer one expected result, such as a known test attendee, to check before using the report.

What attendees see

Nothing changes in the app because of a token. Data a partner adds or changes through the Core API appears in your event.

Limits

Organization tokens can update events but can't create or delete them.
Each token can have one scope per resource.
A scope with a Primary record row restriction can't create records.
Brella limits how many requests each token can make per minute. Requests over the limit get error 429.

Troubleshooting

The partner gets error 403 on every request
The token was deleted, rotated or has expired, or the partner is using a personal API key. Check the token's Status, or rotate the token and share the new value.

Error 403 for one resource
The scope for that resource has Enabled turned off, or it doesn't allow the action. Writes need Write and the matching Write actions. If the Write tag in the scope list shows "No write actions granted, so writes are denied", the scope has no write actions. Edit the scope.

Error 404
The token has no scope for that resource, the event isn't in the scope's Specific events, or the organization ID in the address is wrong. Check the scope and the IDs.

Error 400: "is an event-level resource"
The address is missing events/<event ID>/ before the resource name. Add the event ID.

You lost the token value
Brella can't show it again. Select Rotate token and share the new value.

API is missing from the organization sidebar
API access is off for your organization, or you aren't an organization admin. Ask your Brella contact to turn on API access, or ask an organization admin to give you the role.

Give partners scoped API access with organization tokens