Permissions and scopes

Every endpoint that changes tenant data requires a permission, and so does nearly every read. The exceptions are a few team reads that any signed-in user can make: the tenant’s own details (GET /api/v1/tenants/me) and the lists of team members, roles and permissions under /api/v1/team. A user gets permissions from their roles; an API key has a fixed set of permissions, its scope, chosen when it is created.

Permission keys

A permission key has the form service.resource.action, in lowercase, for example catalog.products.read.

Most resources have a pair of keys:

• .read allows reading the resource.
• .manage allows creating, changing and deleting it, and includes .read. A token or key that holds catalog.products.manage can also call every endpoint that needs catalog.products.read.

As a rule, GET endpoints need the .read key and writes need the .manage key.

Registered permissions

Key	Allows
warehouseconfig.facilities.read	View facilities and the warehouse configuration audit trail (/api/v1/audit-entries).
warehouseconfig.facilities.manage	Create, update and delete facilities and set their location code pattern.
warehouseconfig.topology.read	View storage and equipment topology and locations, export topology and read snapshots.
warehouseconfig.topology.manage	Create, update and delete storage nodes, equipment nodes and edges, edit location attributes and import topology.
warehouseconfig.zones.read	View zone profiles, zones and the locations in each zone.
warehouseconfig.zones.manage	Create, update, activate and delete zone profiles and zones, and add or remove zone locations.
catalog.products.read	View products with their units of measure, barcodes and handling rules.
catalog.products.manage	Create, update, bulk upsert, activate, deactivate and delete products with their units of measure, barcodes and handling rules.
inventory.stock.read	View stock positions, the stock summary, the stock ledger, license plates and allocations, and look up a scanned code.
inventory.stock.manage	Receive stock, adjust it in or out with a reason, and put it on hold (quarantine or damaged) and release it.
inventory.movements.manage	Create and delete license plates (pallets, cases and totes), and move stock and license plates within a facility.
inventory.allocations.manage	Allocate stock to order lines by each product’s rotation strategy, pick allocated stock, and release allocations. Viewing allocations needs inventory.stock.read.
inventory.counts.read	View cycle counts and what was found.
inventory.counts.manage	Open and cancel cycle counts.
inventory.count_tasks.manage	Submit what a cycle count found at its location. The count never shows the stock jtWMS expects there.
routing.config.read	View conveyor routing configuration. For plans that include routing.
routing.config.manage	Change conveyor routing configuration. For plans that include routing.
routing.operations.read	View conveyor routing operations. For plans that include routing.
routing.operations.manage	Carry out conveyor routing operations. For plans that include routing.
routing.devices.manage	Let conveyor devices talk to the routing engine, for their API keys. For plans that include routing.
simulator.scenarios.read	View simulation scenarios. For plans that include the simulator.
simulator.scenarios.manage	Create, change and delete simulation scenarios. For plans that include the simulator.
simulator.runs.read	View simulation runs and their results. For plans that include the simulator.
simulator.runs.manage	Start and control simulation runs. For plans that include the simulator.
simulator.credential.manage	Manage the API key the simulator runs with. For plans that include the simulator.
webhooks.subscriptions.manage	Create, view, update, deactivate and delete webhook subscriptions, rotate their signing secrets, and view and redeliver their deliveries.
identity.users.manage	Invite, remove and manage team members, and read the team audit trail.
identity.roles.manage	Create, edit and delete roles and their permissions.
identity.api_keys.manage	Create, list and revoke the tenant’s API keys and choose their permissions.
identity.tenant.manage	Change the tenant’s subscription plan.
identity.sandbox.manage	Create, reset and delete the organisation’s sandbox, and switch into it.

The identity.* endpoints need a signed-in user’s token, so an API key with an identity.* permission can’t use it. See Authentication.

Standard roles

Every tenant has four system roles. They can be assigned but not deleted, renamed or edited; copy one to get an editable role.

Role	Permissions
Tenant Admin	Every permission.
Warehouse Manager	Every warehouseconfig.*, catalog.*, inventory.*, webhooks.* and routing.* permission.
Operator	Every .read permission, inventory.movements.manage, inventory.count_tasks.manage and routing.operations.manage.
Read-Only API Client	Every .read permission.

When jtWMS adds a permission, the system roles whose rule matches it gain it automatically. A user with identity.roles.manage can also create custom roles, from permissions they hold themselves.

API key scopes

When you create an API key, you choose its scope: a list of permission keys. The scope is fixed: it can’t be changed after the key is created. To change what an integration can do, create a new key with the scope you need, move the integration to it, and revoke the old key.

curl -X POST "https://<your-jtwms-host>/api/v1/api-keys" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "ERP product sync",
        "permissions": ["catalog.products.manage"],
        "expiresAt": "2027-10-01T00:00:00Z"
      }'

Field	Rules
name	Required, 1 to 100 characters.
permissions	Required, 1 to 200 permission keys.
expiresAt	Optional. A future date and time; omit it for a key that doesn’t expire.

Creating a key needs identity.api_keys.manage, and follows the subset rule: you can only give a key permissions you hold yourself. Holding a .manage key counts as holding its .read key.

Status	errorCode	Meaning
400	api_key_permission_unknown	A requested key isn’t a registered, active permission.
400	api_key_permission_not_held	You don’t hold a requested permission.
409	api_key_limit_reached	The tenant already has as many usable keys as its plan allows. The limit is in maxApiKeys. Revoke a key or upgrade the plan.

The two 400 responses are validation errors: the errors member lists the offending keys under Permissions. See Errors.

The number of keys a tenant can hold depends on its plan and add-ons. The plans allow 1 key on Free, 3 on Starter, 10 on Pro and any number on Enterprise. Revoked and expired keys don’t count.

When a permission is missing

A request authenticated as a user or a key that lacks the permission an endpoint needs gets 403 Forbidden. Nothing is changed. A 401 instead means the request isn’t authenticated at all: see Authentication.

A user’s permissions are read into their access token when they sign in or refresh. When an administrator changes a user’s roles, their existing access tokens are refused with 401 token_revoked, and refreshing the session or signing in again picks up the new permissions.