Skip to main content

Give partners scoped API access with organization tokens

C
Written by Customer Success

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. Its scopes decide which data, events, fields and actions it can use.

Turn on Enable MCP use to grant the same access to an AI assistant through MCP.

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 with the Core API and, when enabled, MCP. A personal API key works with the Integration API, which the Brella app on Zapier uses. A personal key cannot replace an organization token, or vice versa.

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

Earlier API page on the Organization tokens tab

API tabs including Scopes and the token table with Connection and Scopes columns

How scopes work

A token has no access until you associate an enabled scope. Each scope covers one resource, such as Registrant, Sponsor, Lead or ContentSession.

Scopes belong to the organization. You can reuse one scope across several tokens. Changing or disabling a shared scope affects every token using it, including MCP connections.

Each scope sets:

  • Event access: All events, including events you create later, or Specific events that you select.

  • Actions: Read and any supported write actions, such as Create, Update or Delete.

  • Readable fields: the fields returned when reading records. id is always included.

  • Allowed filters: the filters the integration can use. Allowing a filter does not force the integration to apply it.

  • Writable fields and Write response fields: fields the integration can change and fields returned after a write.

  • Related data, when available: related records and fields the integration can request.

  • Data restrictions, when available: limits on accessible records, such as leads from selected sponsors.

A token can have one scope per resource. To give integrations different access to the same resource, create separate scopes and associate each with the appropriate token.

Create a token

  1. Open API > Organization tokens.

  2. Select Create token.

  3. In Token settings, enter a Name of up to 100 characters, for example "Data warehouse export".

  4. Optional: enter a Description of up to 255 characters.

  5. Optional: choose an Expires date. Leave it empty for a token that never expires.

  6. Open Associated scopes and select existing scopes for the integration. If none are suitable, create them separately under API > Scopes.

  7. Select Create token.

  8. In Store your token, select Copy to clipboard and store the value in a password manager.

  9. Select Close.

Earlier Create token dialog with Name, Description and Expires fields

Current Create token drawer with Token settings, Name, Description, Expires and Associated scopes; no token value

Enable MCP use is off for new tokens. Leave it off for a direct Core API integration. For an AI assistant, see Connect an AI assistant to Brella with MCP.

Note: Images labeled as earlier examples show the previous interface. Current token and scope settings open in separate drawers.

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

Create a reusable scope

  1. Open API > Scopes.

  2. Select Create scope.

  3. In Scope settings, enter a Name and leave Enabled on.

  4. Choose the Primary resource. Reporting resources appear under Analytics. You cannot change the resource after saving.

  5. Under Event access, choose All events, or choose Specific events and select the Events.

  6. Under Start with an access level, choose Read only, Read + write or Custom.

  7. Review the selected actions and expand the sections under Fields & related data to adjust access.

  8. Open Associated tokens and select the tokens that need this scope.

  9. Select Create scope.

The access levels fill in permissions and field selections:

  • Read only selects all readable fields, allowed filters and related data for the chosen resource.

  • Read + write adds all supported write actions except Delete, with all writable fields and write response fields.

  • Custom lets you adjust the existing selections. Choosing it does not clear fields already selected by a preset.

Delete is never selected by a preset. Select it separately only when the integration needs to remove records permanently.

Earlier Add scope drawer with the former Permissions and Read configuration sections

Associate scopes with a token

  1. Open API > Organization tokens.

  2. Select the token name or Edit.

  3. Open Associated scopes.

  4. Select the scopes the token needs and clear any it no longer needs.

  5. Select Save.

You can search by scope or resource. Will add and Will remove show pending changes. Selecting another scope for the same resource asks you to replace the current selection. Review the change, confirm the replacement and select Save.

Removing an association stops that token from using the scope. The scope stays available under Scopes, and other tokens keep their associations.

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.

  1. Create a scope named Autumn Forum attendee report.

  2. Choose Registrant as the Primary resource.

  3. Choose Specific events and select Autumn Forum.

  4. Choose Custom and keep only Read selected among the actions.

  5. Expand Readable fields, select Clear, then select first-name, last-name and email.

  6. Expand Allowed filters, select Clear, then select status.

  7. Expand Related data and clear all selected associations.

  8. In Associated tokens, select the partner's token.

  9. Select Create scope.

Your developer can filter on status to request people who joined. The response contains id, names and email addresses. Granting a filter 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

Create a separate ScanningQuestion scope for the intended event. Choose Custom, clear Read and select Create.

Under Writable fields, select sponsor-id, title and field-type. Add options if the question offers choices. Under Write response fields, select title.

The form requires sponsor-id when granting Create. The developer supplies an existing sponsor ID from that event and a valid question type. Associate the developer's token and select Create scope.

Earlier Write configuration with Create selected and writable question fields

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 Connection, Scopes, Expires, Created and Status. Connection is Core API or Core API + MCP. Expires shows Never for tokens without an expiry date.

  • Edit a token: select its name or Edit, change its settings or associated scopes, and select Save.

  • Rotate a token: open Token settings > Token security, select Rotate token, then Rotate. The old value stops working at once. Copy the new value from Store your new token and update every integration using it. Its scopes stay associated.

  • Delete a token: open its drawer, select Delete token, then Delete. Integrations using it lose access. Its shared scopes remain under Scopes.

  • Change a scope: open API > Scopes, select Edit, make the changes and select Save. Changes apply to every associated token. Turn off Enabled to pause the scope for all of them.

  • Delete a scope: open its drawer, select Delete scope, then Delete. Every associated token loses the access granted by that scope. Deletion cannot be undone.

Check Used by on the Scopes tab and Associated tokens in the scope drawer before changing a shared scope.

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 data 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 associated scope has Enabled turned off, or it does not allow the action. Open API > Scopes, edit the scope and check the selected actions. Changes affect every token using that 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.

Related articles

Did this answer your question?