API Authentication

← Back to Developers

Base URL

All REST API requests go to a single host:

https://api.livecourier.com/v1

This is the only supported base URL. Requests to tenant subdomains (<your-code>.livecourier.com/api/v1/...) return 404 - that host is reserved for the customer portal.

Required Headers

Every request must include two headers:

Header	Value	Purpose
Authorization	Bearer <token>	Authenticates the API user
X-Tenant	CLIENT_ID	Identifies which client's data to access

The Client ID is shown on Settings → API / Web Services and on each customer's API Access section. It is not a secret - it's a public identifier, similar to an account ID.

Setting Up API Access

There are two places to create API users:

Type	Where	Scope
Per-customer	Customer detail page → API Access	Scoped to that customer's data
Tenant-wide	Settings → API / Web Services	Access to the whole tenant

Creating an API User

1. Open the appropriate page (customer detail, or Settings → API / Web Services).
2. Click + New API User / Client.
3. Fill in the form:

Field	Required	Description
Username	Yes	Letters, digits, and . _ @ - only - no spaces
Password	Yes	Minimum 6 characters, no spaces
Email	No	Contact email for reference
Permissions	Yes	Check the permissions this user should have

Click Create - the user is created and a token is issued in the same step. The token is shown once in a modal; copy it immediately.

Important: The raw token is shown only once. The system stores only a SHA-256 hash. If you lose the token, generate a new one and revoke the old.

API Permissions

Each API user can be granted specific capabilities:

Permission	What it allows
Create Shipments	POST /v1/shipments
Read Shipments	GET /v1/shipments/{awb}
Cancel Shipments	DELETE /v1/shipments/{awb}
Tracking	GET /v1/shipments/{awb}/track
Rate Quotes	POST /v1/rates/quote
Labels	GET /v1/shipments/{awb}/label
List Services	GET /v1/services
Create Pickups	POST /v1/pickups
Read Pickups	GET /v1/pickups/{id}
Cancel Pickups	DELETE /v1/pickups/{id}

Permissions can be edited at any time.

Token Authentication

All API requests use Bearer token authentication. No sessions or cookies - the API is fully stateless.

Token Properties

Property	Value
Format	64-character hex string (256-bit random)
Expiration	None - tokens remain valid until revoked (Stripe/Twilio pattern)
Storage	SHA-256 hash only; raw token not recoverable
IP tracking	Last-used IP recorded for auditing

Example Request

curl https://api.livecourier.com/v1/shipments/ABC123 \
  -H "Authorization: Bearer <your-token>" \
  -H "X-Tenant: CLIENT_ID"

Rotating / Revoking Tokens

• Revoke single token - click Revoke next to a token in the API Access section.
• Revoke all tokens for a user - click Revoke Tokens on the user row.
• Deactivate user - toggles the user inactive and revokes all their tokens.
• Delete user - soft-deletes the user and revokes all tokens permanently.

The current token can also be revoked programmatically:

DELETE /v1/auth/token
Authorization: Bearer <your-token>
X-Tenant: CLIENT_ID

Programmatic Login

A token can also be obtained by posting credentials (primarily useful for interactive agents; integrations typically use the long-lived token from the UI):

POST /v1/auth/token
X-Tenant: CLIENT_ID
Content-Type: application/json

{
  "username": "api_user",
  "password": "secret"
}

Response:

{
  "ok": true,
  "data": {
    "token": "abc123...",
    "user": {
      "id": 42,
      "username": "api_user",
      "role": "api_client"
    }
  }
}

Rate Limiting

API requests are rate-limited per user. Default: 60 requests per minute on a 1-minute rolling window. Custom limits are configurable per user. Every response includes X-RateLimit-Limit and X-RateLimit-Reset headers. See Errors & Rate Limits for details.

Activity Log

The API Access section includes a Recent Activity log showing the last 20 API calls. Each entry shows timestamp, username, action, IP address, and details.

Tips

• Create separate API users for different integrations so access can be revoked independently.
• Grant minimum permissions - don't enable "Create Shipments" if the integration only needs tracking.
• Monitor the activity log periodically for unexpected usage patterns.
• Rotate tokens periodically: generate a new token, switch the integration, then revoke the old one.
• Rate quote results respect the customer's linked pricing - per-customer API users inherit that customer's rate tables.

Next: Endpoint Reference →