Permissions
Which permission each API endpoint and dashboard feature needs, and what the default Admin and Member roles include.
- Product
- APIShipping Engine API
- Section
- Reference
- Reading time
- 4 min read
Every user in an organisation has one role, and a role is a list of permission codes. An endpoint
that needs a permission your role doesn't have returns
403 Missing permissions.
Your API key uses the owner's role
An API key belongs to the organisation, but every API call acts as the organisation owner: the user whose business verification created the organisation.
- The key has exactly the permissions of the owner's current role. If an admin changes that role, the key's permissions change on the next request.
- Orders, shipments, balance and balance logs are kept per user. Everything you create through the API belongs to the owner, is paid from the owner's balance, and appears in the owner's dashboard.
- The owner gets the Admin role when the business is approved, so a new key can call every endpoint below. Keep the owner on a role that has at least the permissions your integration uses.
API endpoints
| Endpoint | Permission |
|---|---|
Regions: searchRegions, listProvinces, listCities, listDistricts, listSubdistricts, lookupPostcode | None (no token needed) |
listPackageTypes | None (no token needed) |
listCouriers, listCourierServices | READ_SHIPPING_RATES |
createShippingRates, retrieveShippingRate | READ_SHIPPING_RATES, plus USE_COD when you send codOption |
createOrder | CREATE_ORDER, plus USE_COD when a rate uses COD |
cancelOrder | READ_ORDER |
listShipments, retrieveShipment, trackShipment | READ_ORDER |
cancelShipment | CANCEL_ORDER |
simulateShipmentStatus (sandbox only) | CANCEL_ORDER |
retrieveBalance, listBalanceLogs | None beyond a valid token |
retrieveWebhookEndpoint | READ_WEBHOOKS |
setWebhookEndpoint | MANAGE_WEBHOOKS |
Permission codes
| Code | Allows | Admin | Member |
|---|---|---|---|
READ_SHIPPING_RATES | List couriers and services, request and read shipping rates (API) | Yes | No |
USE_COD | Quote and book cash-on-delivery (COD) shipments | Yes | Yes |
CREATE_ORDER | Create orders (API) and book shipments in the dashboard | Yes | Yes |
READ_ORDER | List, view and track shipments; cancel whole orders (API) | Yes | Yes |
CANCEL_ORDER | Cancel single shipments; simulate statuses in the sandbox | Yes | Yes |
READ_WEBHOOKS | View the webhook endpoint | Yes | No |
MANAGE_WEBHOOKS | Set, change, disable or delete the webhook endpoint | Yes | No |
READ_API_KEYS | View the organisation's API key details in the dashboard | Yes | No |
MANAGE_API_KEYS | Rotate the API key secret | Yes | No |
READ_ORGANIZATION | View the organisation profile and its members | Yes | Yes |
UPDATE_ORGANIZATION | Edit the organisation profile | Yes | No |
MANAGE_MEMBERS | Invite and remove members, change a member's role | Yes | No |
MANAGE_ROLES | Create, edit, delete and assign custom roles | Yes | No |
READ_BANK_ACCOUNTS | View bank accounts for withdrawals | Yes | Yes |
MANAGE_BANK_ACCOUNTS | Add bank accounts and choose the active one | Yes | Yes |
READ_ADDRESS_BOOK | View saved addresses | Yes | Yes |
MANAGE_ADDRESS_BOOK | Add, edit and delete saved addresses | Yes | Yes |
READ_PRODUCT_CATALOG | View the store's product catalog | Yes | Yes |
MANAGE_PRODUCT_CATALOG | Add and edit products, variants, categories and images | Yes | Yes |
MANAGE_USERS | Included in Admin. Not required by any endpoint today. | Yes | No |
READ_INVOICES | Included in Admin. Not required by any endpoint today. | Yes | No |
Admin and Member are the two roles every business organisation starts with. The owner is an Admin. People you invite get the role you choose, or Member (the default role) when you don't choose one. Both roles can be edited.
Custom roles
Anyone with MANAGE_ROLES (Admins by default) can create custom roles from the codes above in the
dashboard's organisation settings, and assign them to members. Other permission codes exist for
Shipping Engine staff and can't be added to an organisation role.
Don't lock out your integration
Removing CREATE_ORDER, READ_ORDER or READ_SHIPPING_RATES from the owner's role stops your API
integration immediately. Change the owner's role only on purpose.
Was this page helpful?