Scopes

The canonical scope list and how to limit each API key to the minimum privilege it needs.

Scopes limit what each API key can do. Issue restricted keys per use case: a read-only key for reporting, a write key for your fulfillment service.

Canonical list

Scope	Allows
`*`	Full access (default for new keys)
`shipments:read`	Read shipments and their details
`shipments:write`	Create and update shipments
`labels:read`	Read label details
`labels:write`	Purchase labels (including one-call buy, which also requires `shipments:write`)
`addresses:read`	Read saved addresses
`addresses:write`	Create and update addresses
`wallet:read`	Read wallet balance and transactions
`wallet:write`	Initiate wallet funding
`webhooks:read`	Read webhook endpoints and delivery attempts
`webhooks:write`	Create, update, and delete webhook endpoints
`organizations:read`	Read the organization and its members
`organizations:write`	Update settings and manage members
`api_keys:read`	Read the key list and usage logs
`api_keys:write`	Create, update, rotate, and revoke keys
`rates:read`	Fetch rates
`carrier_preferences:write`	Configure enabled carriers and your own account’s credentials
`carrier_services:read`	Read the service catalog
`tracking:read`	Read tracking events
`trackers:read`	Read registered trackers
`trackers:write`	Register and delete trackers
`orders:read`	Read orders
`orders:write`	Create, update, cancel, and delete orders
`batches:read`	Read batches
`batches:write`	Create batches and manifests
`products:read`	Read the product catalog
`products:write`	Create, update, and delete products
`notification_settings:read`	Read recipient-notification toggles, branding, and templates
`notification_settings:write`	Update notification toggles, subjects, and branding
`shipping_rules:read`	Read and preview automation rules
`shipping_rules:write`	Create, update, reorder, and delete rules
`insurance_claims:read`	Read insurance claims
`insurance_claims:write`	File claims and administer their status

How enforcement works

Dashboard sessions have implicit full access. Scopes apply to API keys.
A key with scopes: ["*"] can access everything.
If a key is missing a required scope, the request returns 403 INSUFFICIENT_SCOPE with the missing scopes listed in details.

Create restricted keys

curl -X POST https://api.sendit.mx/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fulfillment service",
    "environment": "LIVE",
    "scopes": ["shipments:read", "labels:write"]
  }'

Restrict by IP (optional)

Beta This feature is in beta. Its behavior may change before the final release.

Limit a key to specific IPs or CIDR blocks. By default the list is empty (all IPs allowed):

curl -X POST https://api.sendit.mx/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fulfillment server",
    "scopes": ["labels:write"],
    "ipAllowlist": ["203.0.113.0/24", "198.51.100.42"]
  }'

Requests from IPs outside the list return 403 IP_NOT_ALLOWED.

Rotate keys with a grace window

Rotation creates a replacement with the same scopes and IP allowlist. The old key stays valid for 24 hours so in-flight requests can drain:

curl -X POST https://api.sendit.mx/v1/api-keys/{id}/rotate \
  -H "Authorization: Bearer <jwt>"

During the window you see both keys in GET /v1/api-keys: the rotating one and the new one.