Docs menu

Scopes and roles

Each operation names the scopes it needs. A person's roles decide which scopes they hold.

Scopes

A scope is an area of the organization's data and how far you can reach into it: stock:read sees stock, stock:write changes it. Write includes read.

The areas are:

products, catalogs, stock, receiving, allocations, locations, orders, shipping, payments, purchasing, customers, companies, privacy, financials, books, margins, reports, imports, integrations, setup, billing, activity, settings, notifications, saved-views, commissions, catalog-override, printing.

What an operation needs

Every operation's page says what it needs under Access, in one of four forms:

Requires stock:write or products:write.
Any one of the listed scopes is enough. Reads often list several.
Requires a signed-in session: …
Any token for the organization. The sentence says what the operation checks instead, such as "an owner or admin".
Requires a platform administrator.
Manifold's own staff only. No role in an organization grants it.
Public: …
No Manifold token is checked by the usual rule. The sentence says what guards it instead: often nothing, sometimes another credential, such as a service credential or a provider's signature.

The service checks this before it does anything. The requirement on the page is the one the service enforces: both are read from the same declaration, so they cannot disagree.

A token without any of the scopes is refused 403, naming what would do:

Response · 403 
{
  "_tag": "ScopeRequired",
  "required": [
    "stock:write",
    "products:write"
  ]
}

Do not retry it. Show the person which scope is missing and ask an owner or admin for a role that holds it.

To see what a token holds, decode its payload (the middle part of the JWT). roles lists the person's roles; the roles below give the scopes each grants. An agent's token also carries agentScopes, the scopes the person chose for it.

Roles

A person holds scopes through roles. A role is a fixed set of scopes; organizations cannot define their own. A person can hold several roles, and holds every scope any of them grants.

Owner
Owns the organization: everything, always.
Admin
Runs the organization: everything, always.

Owner and admin hold every scope, always. The other roles are assigned:

Each role's scopes, read from the platform's own table. Changes is :write, which includes reading; Reads is :read only. Interfaces are the screens the role can open.

RoleChangesReadsInterfaces
Fulfilment fulfilmentPicks, packs and ships orders.orders, shipping, allocations, notifications, saved-views, printingstock, products, locations, customers, companies, settingspick-pack, back-office
Receiving receivingBooks deliveries in against purchase orders.receiving, saved-views, printingpurchasing, stock, products, locations, companies, settingsreceiving, back-office
Stock control stock-controlCounts, adjusts, transfers and writes off stock.stock, saved-views, printingproducts, locations, settingsstocktake, back-office
Purchasing purchasingRaises purchase orders, supplier invoices and landed costs.purchasing, companies, customers, notifications, saved-viewsstock, products, catalogs, locations, settingsback-office
Merchandising merchandisingKeeps the catalog, prices and sales channels.products, catalogs, integrations, customers, companies, saved-views, printingstock, locations, orders, settings, marginsback-office
Finance financeValuation, COGS, the ledger, payments and locking the books.payments, reports, notifications, bookssaved-views, commissions, financials, margins, orders, shipping, purchasing, products, catalogs, stock, customers, companies, locations, settingsback-office, reporting
Store storeSells across the counter.orders, payments, allocations, customers, notifications, printingproducts, catalogs, stock, locations, settingspos, back-office
Wholesale rep wholesale-repTakes wholesale orders for companies; never sees cost or margin.orders, allocations, companies, customers, notifications, saved-viewsproducts, catalogs, stock, locations, settingsb2b-order-form, back-office
Sales manager sales-managerTakes wholesale orders like a rep, sees their cost and margin and the stock on order, approves a rep's sale below the minimum margin, and sells outside a customer's catalogs.orders, allocations, companies, customers, notifications, saved-views, margins, catalog-overrideproducts, catalogs, stock, locations, settings, purchasingb2b-order-form, back-office
Analyst analystReads and builds reports.reportssaved-views, orders, products, catalogs, stock, purchasing, customers, companies, locationsreporting
Data migration data-migrationImports and exports data in bulk.imports, products, catalogs, stock, receiving, allocations, purchasing, orders, payments, customers, companies, locations, saved-viewssettingsback-office
Support supportAnswers customers: finds their orders, edits, cancels and refunds them, resends messages.orders, payments, customers, companies, notifications, saved-viewsproducts, catalogs, stock, shipping, locations, settingssupport-desk, back-office
Operations lead ops-leadRuns the warehouse floor: throughput, exceptions, stations.allocations, shipping, orders, saved-views, printingstock, products, locations, settings, purchasing, customers, companiesops-board, pick-pack, back-office

For example, an integration that creates orders, records payments and receives stock needs orders:write, payments:write and receiving:write: Store and Receiving together. Each operation's Access says exactly what it asks.

A member with no roles holds nothing. They can sign in, but every operation that needs a scope refuses them.

An owner or admin assigns roles in Settings › Users: Edit beside the member's roles. Through the API, send the whole set; it replaces what the member had:

curl 
curl -X PUT 'https://auth.getmanifold.io/api/auth/roles/org_0199f3a2-7c4e-7b1a-9d3e-5f6a7b8c9d0e/usr_0199f3a2-a1b2-7c3d-8e4f-5a6b7c8d9e0f' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "roles": [
    "fulfilment",
    "receiving"
  ]
}'

The member's next token carries the new roles. Sending the set they already hold, in any order, changes nothing and records nothing. For the screens, see People and roles.

Views

A view is a whole interface, such as the pick-pack station or the pos register. A view is chosen at sign-in, on a station or register, and its token then carries it. The view caps what the token can do, whatever the person's roles: a register cannot read the ledger. Owners and admins are never capped.

An API token normally carries no view, so you can leave views aside.

Nobody grants more than they hold

Whenever someone passes access on, it is checked against what they hold themselves:

  • Assigning roles. Roles that reach past the assigner's own are refused 403 GrantExceedsYours, naming the excess.
  • Installing an app. The app gets everything it asks for, from someone who holds all of it, or the install is refused 403 GrantExceedsYours. See App tokens.
Response · 403 · assigning roles or installing an app 
{
  "_tag": "GrantExceedsYours",
  "scopes": [
    "orders:write"
  ],
  "views": [
    "pick-pack"
  ]
}
  • Connecting an AI agent. You choose its scopes from those you hold. Scopes you do not hold are dropped, not refused; a request with none you hold is refused 400 AgentGrantEmpty. The agent holds only the overlap of your scopes and its grant, so if your roles shrink, so does its reach. Owners and admins are narrowed by the grant too.

Apps

An app holds no roles. Its token carries exactly the scopes its installation was granted, and the same Access rule applies to every call it makes. The webhooks it can receive are held to the same scopes: order.created needs orders:read. See Webhooks.

Reference