Authentication

All API requests require a Bearer token in the Authorization header.

curl -H "Authorization: Bearer pr_live_YOUR_KEY_HERE" \
  https://api.packageretriever.com/v1/wallet

API key types

Prefix	Environment	Billing	Labels
`pr_live_`	Production	Real charges from wallet	Real, mailable labels
`pr_test_`	Sandbox	No charges	Simulated labels (not mailable)

Both key types use the same endpoints and return the same response shapes. The only difference is whether real carrier APIs are called and whether your wallet is charged.

Creating API keys

Log in to your Package Retriever dashboard
Open Apps & Tools from your profile menu
Go to the Unleashed tab
Click Create Key
Choose environment (Live or Sandbox) and permissions
Copy the key immediately — it won’t be shown again

Scopes

Each key has permissions (scopes) that control what it can access:

Scope	What it gates
`rates:read`	Rate shopping
`labels:write`	Creating and voiding labels
`labels:read`	Viewing labels and downloading PDFs
`tracking:read`	Tracking queries
`addresses:read`	Address validation
`carrier-accounts:read`	Viewing connected carrier accounts
`batches:write`	Creating and processing batches
`batches:read`	Viewing batch status
`wallet:read`	Viewing wallet balance

If a request requires a scope your key doesn’t have, you’ll receive:

{
  "error": {
    "code": "AUTH.KEY.INSUFFICIENT_SCOPE",
    "message": "This key does not have the 'labels:write' scope required for POST /v1/labels.",
    "suggestion": "Update this key's scopes in your dashboard or create a new key with 'labels:write'.",
    "required_scope": "labels:write",
    "key_scopes": ["rates:read", "tracking:read"]
  }
}

Rate limit headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1684000000
X-Request-Id: req_k3m9d2f1x

The X-Request-Id is unique per request. Include it when contacting support.

Key rotation

To rotate a key without downtime:

Create a new key with the same scopes
Update your application to use the new key
Verify the new key works
Revoke the old key

Keys can be revoked instantly from the dashboard. Revoked keys return AUTH.KEY.REVOKED immediately.

Get Started

Guides

Migrate

Reference

Authentication

Authentication

API key types

Creating API keys

Scopes

Rate limit headers

Key rotation

​Authentication

​API key types

​Creating API keys

​Scopes

​Rate limit headers

​Key rotation

Authentication

API key types

Creating API keys

Scopes

Rate limit headers

Key rotation