Scopes & Permissions

Control what your app can access on the JTL Platform

Scope enforcement requires JTL-Wawi 2.2.0 or higher. On earlier versions, declared scopes are validated at registration but do not restrict API calls.

Every JTL integration must declare which platform resources it needs access to. The JTL Platform uses scopes: permission strings that describe the read, write, or print access an app is requesting against specific API resources.

How you declare scopes depends on the environment:

Environment	Where scopes are declared	Format
Cloud	Manifest, in capabilities.erp.api.scopes	resource.permission
OnPremise	App registration POST request	resource.permission

In both cases, the principle of least privilege applies, meaning you should request only the scopes your app actually needs.

How Scopes are Enforced

Scopes are validated when the app is registered in both environments and enforced at the API layer when your app makes a request. The access rules for a request depend on the token used.

Token	Obtained by	What governs access
Access token	Client credentials, using the app’s service account	The scopes declared in the manifest
App token	AppBridge in an embedded app, or browser sign-in on your own domain	The signed-in merchant’s own JTL-Wawi permissions

Access tokens are governed by the scopes declared in the app’s manifest. When an app calls the API with an access token, it acts as itself, and access is limited to those scopes.

App tokens used by embedded apps in Cloud ERP follow a similar pattern. However, when an app makes API calls on behalf of a signed-in merchant, access is governed by that merchant’s own JTL-Wawi permissions.

See App Token Authentication and Service Account Authentication for details on each token.

Installation Grants Your Scopes

Installation is what grants your app its scopes, and it happens per organization. When an admin installs your app, the platform grants it the scopes declared in your manifest. That set becomes the maximum scope set for tokens issued for that organization.

There is no separate consent screen for individual scopes. Installing the app accepts the scopes it declares. See App Installation Flow.

Access follows the installation. A token issued for an organization that has not installed your app carries none of your scopes, so API calls are refused. This applies to every token type, including tokens issued when a user signs in with their JTL ID. The user can access your app’s data only for an organization where your app is installed. See Standalone Authentication.

The scopes granted to an organization are included in the token as the urn:jtl:api_scopes claim. This claim shows the scopes available to that token. See API Keys & Tokens for details.

Anatomy of a Scope

Every scope follows the pattern resource.permission.

Component	Description	Examples
resource	The API domain your app needs	items, orders, customers, inventory
permission	The access level	read (GET), write (POST/PATCH/DELETE), print (PDF/print endpoints)

Permissions do not include each other. write does not imply read, and print does not imply either. If your app needs to read items, modify them, and generate printed documents, declare all three: items.read, items.write, items.print.

Available Scopes

The table below is generated from the latest cloud OpenAPI spec. Any value outside this list is rejected at registration in both Cloud (manifest validation) and OnPremise (registration POST).

Sales

Scope	Description
customers.read	Grants permission to read customer data.
customers.write	Grants permission to create and modify customer data.
items.read	Grants permission to read item data.
items.write	Grants permission to create and modify item data.
orders.read	Grants permission to read orders.
orders.write	Grants permission to modify marketplace order data (exclude/reset cancellation, payment, return and shipping uploads).
returns.read	Grants permission to read returns.
returns.write	Grants permission to create and modify returns.
saleschannels.read	Grants permission to read sales channels.
saleschannels.write	Grants permission to create and modify sales channels.
salesorders.print	Grants permission to print and output sales orders.
salesorders.read	Grants permission to read sales orders.
salesorders.write	Grants permission to create and modify sales orders.
salesquotations.print	Grants permission to print and output sales quotations.
salesquotations.read	Grants read access to sales quotations.
salesquotations.write	Grants write access to sales quotations.

Inventory and Fulfilment

Scope	Description
deliveries.read	Grants permission to read deliveries.
deliveries.write	Grants permission to create and modify deliveries.
deliverynotes.print	Grants permission to print and output delivery notes.
deliverynotes.read	Grants permission to read delivery notes.
deliverynotes.write	Grants permission to create and modify delivery notes.
inventories.read	Grants permission to read stock levels.
inventories.write	Grants permission to modify stock levels.
inventory.read	Grants permission to read stock levels.
inventory.write	Grants permission to modify stock levels.
labels.read	Grants permission to read labels.
labels.write	Grants permission to create and modify labels.
picklists.read	Grants permission to read pick lists.
picklists.write	Grants permission to create and modify pick lists.
warehouse.read	Grants permission to read warehouse data.

Finance

Scope	Description
currencies.read	Grants read access to currencies.
invoices.print	Grants permission to print marketplace external documents (invoices, credit notes).
invoices.read	Grants permission to read invoices.
invoices.write	Grants permission to create and modify invoices.
paymentmethods.read	Grants read access to payment methods.
salesinvoicecorrections.print	Grants permission to print and output invoice corrections.
salesinvoicecorrections.read	Grants permission to read invoice corrections.
salesinvoicecorrections.write	Grants permission to create and modify invoice corrections.
salesinvoices.print	Grants permission to print and output sales invoices.
salesinvoices.read	Grants read access to sales invoices.
salesinvoices.write	Grants write access to sales invoices.
taxes.read	Grants permission to read tax data.
taxes.write	Grants permission to create and modify tax data.

System

Scope	Description
all.read	Allows the application to read all data.
application.runas	Allows the application to execute requests on behalf of another user.
customfields.read	Grants permission to read custom fields.
customfields.write	Grants permission to create and modify custom fields.
extensibility.integration	Grants permission to manage extensions and integrations of the JTL-Wawi.
jera.read	Grants read access to JERA internal endpoints.
system.config.read	Grants permission to read the system configuration.
system.config.write	Grants permission to modify the system configuration.
system.worker.read	Grants permission to read the configuration and status of background workers.
system.worker.write	Grants permission to configure and control background workers.
wawiapp.all	Grants access to Wawi app related operations.

Other

Scope	Description
channels.read	Grants permission to read marketplace channels.
marketplaceoffers.read	Grants permission to read marketplace offers and offer failures.
marketplaceoffers.write	Grants permission to create and modify marketplace offers.
masterdata.read	Read master data such as shipping methods, payment methods, color codes and tax classes.
masterdata.write	Write master data
notifications.read	Grants permission to read marketplace notifications.
payments.read	Grants read access to payments.
payments.write	Grants write access to payments.
pps.read	Grants permission to read production data.
pps.write	Grants permission to create and modify production data.
procurements.read	Grants permission to read procurement data.
resources.read	Grants permission to read resource management data.
resources.write	Grants permission to create and modify resource management data.

Cloud Scopes

For Cloud, you declare API scopes in your app.json under capabilities.erp.api.scopes. These scopes determine which JTL-Wawi API endpoints your app can call.

Declaring Scopes in the Manifest

{
  "capabilities": {
    "erp": {
      "api": {
        "scopes": [
          "items.read",
          "items.write"
        ]
      }
    }
  }
}

Capability-level Permissions

Beyond API scopes, Cloud Apps can enforce granular permissions on individual capabilities like panels. This lets you scope specific UI surfaces to a smaller subset of resources than the app as a whole.

Panel Permissions

Use requiredScopes on a panel definition to control resource access:

{
  "capabilities": {
    "erp": {
      "pane": [
        {
          "id": "inventory-insights",
          "context": "items",
          "url": "https://example.com/panel/inventory",
          "requiredScopes": ["items.read", "salesorders.read"]
        }
      ]
    }
  }
}

requiredScopes accepts the same scopes listed above.

OnPremise Scopes

For OnPremise integrations, scopes are declared during app registration via the REST API. You include them in the mandatoryApiScopes and optionalApiScopes arrays of the registration request.

Registering with Scopes

The example below registers an app that requires two scopes and optionally uses one more.

curl -i -X POST \
  "http://127.0.0.1:<port>/api/eazybusiness/authentication" \
  -H "Content-Type: application/json" \
  -H "api-version: 2.0" \
  -H "x-appid: MyApp/1.0.0" \
  -H "x-appversion: 1.0.0" \
  -H "x-challengecode: MyChallengeCode" \
  -d '{
    "appId": "MyApp",
    "displayName": "My App",
    "description": "Inventory management tool",
    "version": "1.0.0",
    "providerName": "My Company",
    "providerWebsite": "https://example.com",
    "mandatoryApiScopes": [
      "items.write",
      "salesorders.read"
    ],
    "optionalApiScopes": [
      "returns.read"
    ]
  }'

Fetching Registration Status and Granted Scopes

After registering, the API returns a registrationId. Poll the registration status endpoint with this ID to retrieve your API key and confirm which scopes were granted:

curl -i -X GET \
  "http://127.0.0.1:64110/api/eazybusiness/authentication/{registrationId}" \
  -H "api-version: 2.0" \
  -H "x-challengecode: MyChallengeCode"

The response contains your API key and the scopes attached to it:

{
  "requestStatusInfo": {
    "appId": "MyApp",
    "registrationRequestId": "abc-123",
    "status": 0
  },
  "token": {
    "apiKey": "00000000-0000-0000-0000-000000000000"
  },
  "grantedScopes": [
    "items.write",
    "salesorders.read",
    "returns.read"
  ]
}

The API key is shown only once in this response. Store it securely, as it cannot be retrieved again. All future API requests use this key in the Authorization: Wawi <API-Key> header.

The grantedScopes array tells you exactly which permissions your app received. If any of your optionalApiScopes were not granted, they will be absent from this array. Your app should check grantedScopes and adapt its functionality accordingly.

Mandatory vs. Optional Scopes

Field	Description
mandatoryApiScopes	Scopes your app requires to function.
optionalApiScopes	Scopes your app can use but doesn’t require.

Use mandatory scopes for core functionality and optional scopes for enhanced features that can degrade without breaking core functionality.

Updating Scopes After Registration

Cloud

Cloud Apps support updating scopes by modifying your app.json. Update the capabilities.erp.api.scopes array, then re-submit the updated manifest through the Partner Portal.

What happens to existing installations depends on whether you add or remove a scope:

• Adding a scope: Existing installations keep the scopes they already granted. The new scope becomes active for an existing installation only after an admin re-consents to it in the Hub. New installations receive the updated scope set immediately. Until an admin re-consents, API calls that require the new scope return 403 Forbidden. Treat the new capability as optional until the scope appears in the token’s urn:jtl:api_scopes claim.

• Removing a scope: The scope is removed from every installation automatically when you publish the update. No re-consent is required because the change only removes access. Tokens stop carrying the removed scope on their next refresh.

OnPremise

OnPremise apps cannot modify scopes on an existing registration. If your app needs additional scopes, you must re-register the app with the updated scope list. This generates a new API key and the old key is invalidated.

Plan your scopes carefully before initial registration. Use optionalApiScopes for features you may need later to avoid forcing a re-registration.

Best Practices

Request minimal scopes. Only declare scopes your app actually uses.

Separate read, write, and print. If your app only displays data, request read only. Add write when your app modifies resources. Add print only when you need to print.

Avoid all.read. Use granular scopes wherever possible.

Use optional scopes for progressive features (OnPremise). If your app has optional features that need extra permissions, put those in optionalApiScopes so the core app still works without them.

Document your scopes for merchants. In your App Store listing and support docs, explain why your app needs each scope. Transparency builds trust.

Handle permission errors. A call that exceeds your declared scopes, or the merchant’s own permissions, returns 403 Forbidden. Catch it and show the merchant which feature is unavailable rather than surfacing the raw error.

What’s Next

OAuth 2.0 Flow

Understand how tokens and scopes work together in the authentication flow.

API Keys & Tokens

Reference for all credential types across Cloud and OnPremise.

Error Handling

Handle permission errors and scope-related 403 responses.

App Manifest Reference

Full app.json schema including all capability fields.