Scopes
A scope says what a token may be used for. A call needs its scope and the privileges and account permissions of the user or service account behind the token. A scope never adds a privilege: a Viewer's token with orders:write still cannot enter orders (and the consent screen does not offer it).
| Scope | Allows |
|---|---|
firm:read | Read the firm's settings |
firm:write | Change the firm's settings (Admins) |
users:read | Read users, roles and privileges |
admin:users | Invite users, change roles, privileges and status (Admins) |
entitlements:read | Read per-account permissions |
entitlements:write | Change per-account permissions (Admins) |
access_reviews:read | Read access reviews |
access_reviews:write | Start and sign off access reviews |
reference:read | Read securities, issuers, accounts, groups, models, benchmarks, brokers, lists and user-defined fields |
reference:write | Create and change reference data, models, groups, lists and user-defined field values |
udf:admin | Define user-defined fields (Admins) |
portfolio:read | Read positions, lots, cash, drift and risk |
portfolio:write | Propose rebalances and what-ifs; move simulated cash |
market:read | Read prices, FX rates, corporate actions and as-of history |
orders:read | Read orders, executions and blotter views |
orders:write | Create, amend, cancel, release and allocate orders; save blotter views |
orders:approve | Approve or reject orders and overrides (four eyes always applies) |
pipeline:read | Read intent-pipeline runs and proposals |
pipeline:write | Start and run intent-pipeline requests and create their orders |
compliance:read | Read rules, versions, packages, violations, overrides and the register |
compliance:rules:write | Draft rules, run the test bench, submit for sign-off |
compliance:rules:approve | Sign off compliance rules (a person, with a confirmation token) |
compliance:violations:write | Acknowledge, resolve, waive and escalate violations |
compliance:reports:read | Generate and read compliance reports and the register PDF |
surveillance:read | Read surveillance and anomaly alerts |
surveillance:write | Update surveillance alerts |
workflow:read | Read workflow items, rules, desks, SLAs, views and my work |
workflow:act | Claim, release, reassign, escalate, prioritise and comment on workflow items |
workflow:rules:write | Draft workflow rules, run the test bench, submit for sign-off |
workflow:rules:approve | Sign off workflow rules (a person, with a confirmation token) |
data:read | Read data loads, batches, bundles, feeds, schedules, jobs, start-of-day status and data quality |
data:write | Apply, undo and discard batches; review held feed files |
events:read | Read the event log and verify its hash chain |
ai_log:read | Read the AI interaction log |
ai:use | Ask the copilot and plan natural-language commands (AI outputs are proposals) |
commands:execute | Execute a previewed natural-language command (with its confirmation token) |
webhooks:read | Read webhooks and their deliveries |
webhooks:write | Configure webhooks and redeliver (Admins) |
admin:api | Manage OAuth clients, service accounts and API settings (Admins) |
owner:inquiries | The site owner's inquiries (site administrators only; never in a firm's tokens) |
data:load:<data set> | Load one data set, e.g. data:load:prices (one scope per data set) |
Which scope an endpoint needs
Each endpoint names its scope in the API reference and in the OpenAPI document (x-required-scope). Without it the answer is 403 with the code insufficient_scope and a WWW-Authenticate: Bearer error="insufficient_scope", scope="..." header.
Accounts you cannot see
Lists hold only the accounts (and their orders, positions and violations) the identity is entitled to. Asking for one you cannot see, or one of another firm, answers 404, exactly like one that does not exist.