Configure token scopes

Choose exactly which data and operations an integration can access.

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

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:

[
  { "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

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.

{
  "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.