Scope a token

Every Airbrx token — personal access token or JWT — carries a scope cube along four axes: method × path × tenant × account. The cube describes the API calls the token is allowed to make. Pick the smallest cube that lets the job run.

The four axes, one at a time

Method

The HTTP method: GET, POST, PUT, DELETE. Read-only jobs should be GET. A "this script will only fetch summaries" token has no business posting rules.

The most common methods to grant explicitly:

• GET — read anything in the granted path/tenant/account.
• POST — create resources (rules, markers, invites).
• PUT — update resources.
• DELETE — remove resources.

Path

The endpoint families this token can hit. The App's API explorer organizes endpoints by tag — analytics, rules, markers, tenants, accounts, team — and the path axis follows those groupings.

Three common path slices:

• /analytics/* — read traffic, savings, summaries.
• /config/tenants/* — read and write tenant configuration, including rules and adapters.
• /markers/* — post and delete invalidation markers.

The mint form supports both broad selections (all endpoints under a tag) and exact-path overrides for tighter control.

Tenant

Which tenants the token can act on. Most automation runs against a single tenant; some (centralized reporting, a consultant who manages many tenants) legitimately need more. The mint form lets you pick a specific tenant, a list of tenants, or "all tenants on this account."

Account

Which accounts the token can act on. This axis matters when a single Airbrx login spans multiple accounts — typically consultants and platform-admins. Most users have a single account, and the axis collapses to that.

Worked examples

Analytics export, one tenant, read-only

A script pulls the analytics endpoints once a day and lands the data in a warehouse for custom reporting.

• Method: GET
• Path: /analytics/*
• Tenant: one tenant
• Account: the owning account

Marker poster for an ETL job

An ETL platform posts a marker after each load. No reads required, no writes outside the markers endpoint.

• Method: POST
• Path: /markers (just one)
• Tenant: one tenant
• Account: the owning account

Rules sync from a config repo

A CI job reads rule files out of a git repo and pushes them to the API. Bidirectional — reads existing rules to diff, writes the new ones.

• Method: GET, PUT, DELETE
• Path: /config/tenants/*/rules/*
• Tenant: the production tenant
• Account: the owning account

Consultant managing several tenants under their own account

A consultant has been invited to several tenants under a client account; they author rules across all of them.

• Method: GET, PUT, POST, DELETE
• Path: /config/tenants/*
• Tenant: all granted tenants
• Account: the client account (not the consultant's own)

Anti-patterns

• "All methods" because it's easier. The cost of picking GET-only when you only read isn't a setting you change later; it's a class of incidents you never have.
• "All tenants" because you might add more later. Re-mint with broader scope when you do. Speculative scope expansion outlasts the speculation.
• "All paths" because you don't know which endpoints you'll need. If you don't know what your script does yet, you don't need a token yet.
• Reusing one token for two scripts. Mint one per job. Revocation isolation is worth the extra minute.

Plan-level restrictions still apply on top

The scope cube is a ceiling, not a floor. Even a token with broad scope can't do things the account's plan doesn't allow — a Free account doesn't get rules-admin endpoints, regardless of how the token is scoped. The API enforces both layers; you don't need to mirror plan logic in your scripts.

Where to go next

• Create a personal access token — the mint flow.
• Exchange a PAT for a JWT — when a short-lived JWT is the better runtime credential.
• Security posture — concept-level treatment of the cube.