---
title: "Configure token scopes"
description: "Choose exactly which data and operations an integration can access."
lastModified: "2026-08-21"
---

Organization administrators configure Core API tokens in Brella's Admin Panel. The normal setup flow is:

1. Create an organization API token and securely save the token value. The secret is shown only when the token is created or rotated.  
2. Add a scope and choose its **Primary resource**. The primary resource cannot be changed after the scope is created.  
3. Enable **Read**, **Write**, or both, where the selected resource supports those operations.  
4. Choose all organization events or specific events. An empty event selection in the underlying scope means all events belonging to the organization.  
5. Configure the read and write policy described below.  
6. Enable the scope and save it.

Deleting a token revokes all of its scopes. Rotating a token immediately invalidates the old token value while preserving its configuration. A token with an expiry time is rejected after that time.

## Read configuration

| Admin Panel option | Effect |
| :---- | :---- |
| Readable fields | Attributes the API may return. `id` is always included. |
| Query fields | Filters the API caller is allowed to send. |
| Row restrictions | Server-enforced filters that the caller cannot remove or broaden. |
| Included associations | Related resources that may be exposed, optionally with a narrower field set. |

Selecting an association in the Admin Panel does not automatically place its full object in every response. It authorizes relationship linkage; the caller uses `?include=association_name` when the related object is needed.

## Row restrictions

Row restrictions are the main way to give a partner access only to its own data. Depending on the resource, an administrator may restrict by:

- a field, such as sponsor `state` or event `event_type`;  
- an association, such as leads belonging to selected sponsors;  
- primary record IDs, such as a fixed set of sponsor IDs; or  
- a named rule, such as sponsor-owned meetings, RSVPs, sessions, or tracking data.

Restrictions always apply to collection reads, individual reads, updates, and deletes. Records outside the restriction behave as not found. Creates must also satisfy the restriction. A scope restricted to specific primary sponsor records cannot create new sponsors.

The underlying restriction shapes are:

```json
[
  { "field": "state", "values": ["active"] },
  { "association": "sponsors", "values": [103705] },
  { "primary": true, "values": [103705, 103706] },
  { "restriction": "sponsor", "values": [103705] }
]
```

Only selectors advertised for that resource may be used. Values inside one restriction are alternatives, like SQL `IN`; multiple restriction objects are cumulative and must all match.

## Write configuration

| Admin Panel option | Effect |
| :---- | :---- |
| Write actions | The allowed subset of `create`, `update`, and `delete`. Only actions supported by the resource can be selected. |
| Writable fields | Maps a request parameter to a writable resource field or write-only input. |
| Write response fields | Attributes returned after successful `POST` and `PATCH` requests. |

The API internally supports a request-key-to-field mapping. In the usual configuration, both names are the same, for example request parameter `first_name` maps to field `first_name`. If your administrator configures a different request parameter, use that configured parameter instead of the field name shown in this guide.

Required create inputs must be granted before `create` can be enabled. For example, meeting creation requires both `requester_registrant_id` and `receiver_registrant_id`; sponsor-ad creation requires `sponsor_id`.

For technical readers, the Admin Panel stores the selections in a structure like the following. The UI normally creates this configuration; it is shown here to make the enforcement model explicit.

```json
{
  "token_scope": {
    "name": "Leads for selected sponsor",
    "description": "Read and maintain leads for one sponsor",
    "enabled": true,
    "primary_resource": "Lead",
    "permissions": ["read", "write"],
    "event_ids": [319986],
    "settings": {
      "read_fields": [
        "event_id",
        "sponsor_ids",
        "registrant_id",
        "created_by_registrant_id",
        "notes",
        "created_at",
        "updated_at"
      ],
      "read_query_fields": [
        "sponsor_id",
        "registrant_id",
        "created_from",
        "created_to"
      ],
      "read_restrictions": [
        { "association": "sponsors", "values": [103705] }
      ],
      "read_associations": [
        {
          "name": "registrant",
          "fields": ["external-id", "first-name", "last-name", "email"]
        },
        {
          "name": "created_by_registrant",
          "fields": ["external-id", "first-name", "last-name", "email"]
        }
      ],
      "write_actions": ["create", "update", "delete"],
      "write_fields": [
        { "param": "registrant_id", "field": "registrant_id" },
        { "param": "created_by_registrant_id", "field": "created_by_registrant_id" },
        { "param": "notes", "field": "notes" },
        { "param": "sponsor_id", "field": "sponsor_id" }
      ],
      "write_response_fields": [
        "event_id",
        "sponsor_ids",
        "registrant_id",
        "created_by_registrant_id",
        "notes",
        "created_at",
        "updated_at"
      ]
    }
  }
}
```

Names in `read_fields`, `read_query_fields`, `write_fields`, and `write_response_fields` are underscored internal names. Association response-field selections may be written with dashed names, as shown above. IDs in row restrictions can be numbers or strings because restriction values are scalar values; using numbers for database IDs is recommended.