Authentication

How to authenticate with the Package Retriever API using Bearer tokens.

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

1. Log in to your Package Retriever dashboard
2. Open Apps & Tools from your profile menu
3. Go to the Unleashed tab
4. Click Create Key
5. Choose environment (Live or Sandbox) and permissions
6. 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:

1. Create a new key with the same scopes
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key

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