ShipWave API Scopes Explained

Why scopes matter

When you hand an API key to an AI agent, a Zapier automation, or a third-party app, you almost never need to grant full account access. Scopes let you give exactly the permissions a job needs — nothing more. If the key leaks, the blast radius is limited to what that key could do.

The scope namespace

Scopes follow the pattern verb:resource. The verbs are:

read: — fetch and list
write: — create, update, delete
manage: — configure (settings, rules, integrations)

The resources are things like orders, shipments, returns, inventory, labels, rules, warehouses, billing, and users. For example, read:orders lets a key list and fetch orders but not create or update them.

Common scope bundles

Read-only reporting key: read:orders, read:shipments, read:returns, read:inventory. Label-buying agent: add write:labels. Returns specialist: read:orders, read:shipments, write:returns, write:labels. Full ops agent: add manage:rules and write:orders. Avoid granting manage:billing or manage:users to agents unless you have a specific reason.

Creating a scoped key

Go to Admin → Settings → API Keys → Create key. Name the key, then check the boxes for each scope you want. The UI shows a plain-English summary at the bottom (e.g. "This key can read orders and shipments and create return labels.") so you can sanity-check before saving. Once created, the key is shown only once — copy it immediately.

Wildcard scopes (legacy)

For backwards compatibility, the wildcards read:*, write:*, and * still work. We recommend granular scopes for any new key. Old keys created before scopes shipped are automatically grandfathered to *; you can rotate them to a narrower scope set at any time.

Auditing scope usage

Each API key page shows the last 30 days of activity grouped by endpoint, so you can see which scopes are actually being used. If a key is granted write:returns but has never created one, consider revoking that scope. The AI Audit Log shows the same data for MCP and Ask ShipWave calls.

FAQs

Can I change scopes on an existing key?

Yes. Edit the key in Admin → Settings → API Keys. Changes take effect within ~10 seconds (we cache the scope set briefly for performance).

What scope does Ask ShipWave use?

Ask ShipWave uses your user-level permissions, not an API key. The same scope checks apply — if your team role does not grant write:returns, the assistant cannot create return labels for you either.

Are there scopes for marketplace operations?

Yes: read:listings, write:listings, and manage:channels. write:listings covers pushing updates to Amazon, eBay, Walmart, etc. manage:channels covers connecting/disconnecting marketplaces.

What if my agent gets a 403?

It means the scope check failed. The error body includes which scope is missing (e.g. requiredScope: "write:labels"). Add it to the key, retry.

API scopes explained