Authentication
Learn how to authenticate with the Parsel API using Bearer tokens.
Bearer Authentication
All requests to the Parsel API must include an authorization token in the HTTP headers. This token verifies your identity and determines your access permissions.
Header Format
Include your API key in the Authorization header using the Bearer scheme:
Authorization: Bearer <your_token>cURL example
curl https://api.parsel.app/billing/invoices \
-H "Authorization: Bearer <your_token>"A missing or invalid token returns 401 Unauthorized.
Obtaining an API Key
During developer preview, API keys are provisioned manually by the Parsel team.
To obtain your API key:
- Create an account on the Parsel platform
- Contact our engineering team at engineering@getparsel.com
- Once approved, our team will share your API key with you
Scopes
Every API token carries a set of scopes, and every endpoint requires one. A request whose token lacks the scope an endpoint needs gets a 403 Forbidden with a required_scope field naming what's missing — see Errors.
Scopes come in READ_*/WRITE_* pairs per resource area, except Billing and Rate shopping profiles, which are read-only in the public API today and so have no WRITE_* counterpart:
| Scope | Grants |
|---|---|
READ_SHIPMENTS | List/get shipments and shipping labels, tracking. |
WRITE_SHIPMENTS | Create/cancel shipments, buy rates, verify addresses. |
READ_BILLING | List/get invoices and line items. |
READ_RATE_SHOPPING_PROFILES | List/get rate shopping profiles. |
READ_WEBHOOKS | List/get webhook subscriptions and their events. |
WRITE_WEBHOOKS | Create/update webhook subscriptions. |
Endpoint reference
| Method | Endpoint | Required scope |
|---|---|---|
GET | /shipments | READ_SHIPMENTS |
POST | /shipments | WRITE_SHIPMENTS |
GET | /shipments/{id} | READ_SHIPMENTS |
PUT | /shipments/{shipment_id}/cancel | WRITE_SHIPMENTS |
POST | /shipments/{shipment_id}/rates/{shipping_rate_id} | WRITE_SHIPMENTS |
POST | /addresses/verify | WRITE_SHIPMENTS |
GET | /shipping_labels | READ_SHIPMENTS |
GET | /shipping_labels/{id} | READ_SHIPMENTS |
GET | /shipping_labels/{shipping_label_id}/track | READ_SHIPMENTS |
GET | /track/{tracking_code} | READ_SHIPMENTS |
POST | /track/bulk | READ_SHIPMENTS |
GET | /billing/invoices | READ_BILLING |
GET | /billing/invoices/{id} | READ_BILLING |
GET | /billing/invoices/{id}/line_items | READ_BILLING |
GET | /rate_shopping_profiles | READ_RATE_SHOPPING_PROFILES |
GET | /rate_shopping_profiles/{profile_key} | READ_RATE_SHOPPING_PROFILES |
GET | /webhooks | READ_WEBHOOKS |
POST | /webhooks | WRITE_WEBHOOKS |
GET | /webhooks/{id} | READ_WEBHOOKS |
PUT | /webhooks/{id} | WRITE_WEBHOOKS |
PATCH | /webhooks/{id} | WRITE_WEBHOOKS |
GET | /webhooks/{id}/events | READ_WEBHOOKS |
Tokens can carry more than one scope. Contact engineering@getparsel.com if your token needs a scope it doesn't have.
Security Best Practices
- Never share your API keys or embed them directly in client-side code
- Store API keys in environment variables or a secure key management system
- Use different API keys for development and production environments