Authentication
Every request carries a secret API key. The key decides the business, the application, the environment and what the request may do.
Sending the key
Put the secret in the Authorization header as a bearer token. Cookies are ignored.
Authorization: Bearer evp_test_…Keep keys on your servers, in environment variables or a secrets manager. Never put one in a website, a mobile app or a code repository. If a key may have leaked, roll or revoke it in the developer portal straight away.
Environments
| Sandbox | Production | |
|---|---|---|
| Key starts with | evp_test_ | evp_live_ |
| Carriers | A test carrier only | The carriers available to your business |
| Money | None | Bookings are paid from your EviPostal wallet |
| Available | Always | After EviPostal turns on production access |
Both use the same address, https://api.evipostal.com/v1. Every sandbox answer has the header EviPostal-Environment: sandbox and every sandbox object has test: true.
Scopes
A key only does what its scopes allow; a missing scope is 403 insufficient_scope. New keys get every scope unless you untick some. GET /me needs no scope.
| Scope | Allows | Endpoints |
|---|---|---|
rates:read | Get shipping rates for a package | POST /rates |
shipments:read | See the shipments this application created | GET /shipments, GET /shipments/{id} |
shipments:write | Book and cancel shipments (production bookings are paid from your wallet) | POST /shipments, POST /shipments/{id}/cancel |
labels:read | Download shipping labels | GET /shipments/{id}/label |
tracking:read | Read tracking status and history | GET /shipments/{id}/tracking |
webhooks:read | See webhook endpoints and past events | GET /webhook-endpoints, GET /events, GET /events/{id} |
webhooks:write | Add and remove webhook endpoints | POST /webhook-endpoints, DELETE /webhook-endpoints/{id} |
Rolling and revoking
- Roll creates a new secret with the same name and scopes. You choose how long the old one keeps working: at once, 1 hour, 24 hours or 7 days.
- Revoke stops a key immediately and for good.
- Each application can have up to 10 working keys per environment. Keys are stored only as a fingerprint: EviPostal cannot show a secret again.
When a key is refused
| Status | Code | Why |
|---|---|---|
| 401 | authentication_required | No Authorization header. |
| 401 | invalid_api_key | The key is not recognised. |
| 401 | api_key_revoked | The key was revoked, or rolled and its time ran out. |
| 403 | insufficient_scope | The key lacks the scope this request needs. |
| 403 | application_disabled | The application is turned off in the portal. |
| 403 | production_access_required | A production key before production access is on. |