API key scopes let you control exactly what each API key can do. When you create a key in the Operator Portal or Seller Portal, you choose which resources the key can access (such as Adverts, Orders, or Refunds) and what level of access it has on each one. A key issued for one purpose can no longer reach into unrelated parts of the API.
What API key scopes are
A scope is a combination of two things: a resource (what part of the API the key can touch) and a level (what the key can do on that resource).
There are three levels:
- Read: The key can retrieve data for the resource.
- Write: The key can retrieve and modify data.
- Manage: The key can retrieve, modify, and perform destructive actions.
Levels are nested. Selecting Manage automatically grants Write and Read. Selecting Write automatically grants Read.
If you leave all scopes unchecked, the key has no access, only public fields will be reachable.
For the full list of resources and the actions each scope grants, see the API Key Scopes playbook in the developer documentation.
What changes for existing integrations
Keys created before scopes existed continue to work without changes. These legacy keys are treated as fully trusted by default, so existing integrations are not affected by the rollout.
Once you have audited your key fleet and confirmed every integration is using a scoped key, you can disable this allowance. See Disable access for legacy unscoped keys below.
Note: If you are running an existing integration and notice unexpected authentication or permission errors, contact Marketplacer support.
Generate a scoped API key in the Operator Portal
- In the Operator Portal, go to Configuration > Marketplacer API Keys.
- In the New API Key section, fill in the key details:
- Description: Enter a unique name and description that reflects the intended use of the key.
- Organization: Enter the legal name of the organization agreeing to the API license.
- Select the checkbox beside I have read and understood the API License.
-
In the Scopes table, select the access level your key needs for each resource:
- Select Read to allow the key to retrieve data.
- Select Write to allow the key to retrieve and modify data.
- Select Manage to allow the key to retrieve, modify, and perform destructive actions.
Tip: Grant the lowest level of access each integration needs. If a key only needs to read data, do not grant Write or Manage.
- Click Create. The API Key window opens showing the generated key. You can only see this value once.
- Copy the key and store it in a safe place.
- Click Close.
Note: You can no longer retrieve the key after you close this panel and browse away from the page.
Disable access for legacy unscoped keys
After you have audited your key fleet and replaced any unscoped keys with scoped ones, you can disable the allowance that grants legacy keys full access.
- In the Operator Portal, go to Configuration > Authentication Settings.
- In the API Keys section, clear the checkbox beside Grant full access to legacy unscoped API keys.
- Save your changes.
Note: Once disabled, all keys created before scopes existed are immediately denied access. These keys cannot be edited to add scopes, so you will need to issue new scoped keys to replace any that should keep working. Treat this as part of your regular API key rotation. See the API Key Rotation playbook for guidance.
Where to learn more
For developer-facing detail on scopes, error responses, and key rotation, see the following playbooks in the API documentation:
- API Key Scopes playbook: Full resource catalogue, level semantics, error shape, and guidance on choosing scopes.
- API Key Rotation playbook: Including scope-rotation guidance.
- Operator and Seller API overview: Getting started with the Marketplacer API.
Related articles