Skip to main content
Shiipp protects every API endpoint with one of two credential types. Dashboard and management endpoints require a short-lived JWT Bearer token issued at login. The public Prealert endpoint used by courier partners accepts a long-lived API key instead. Understanding which method applies to your integration is the first step before making any API call.

JWT Bearer Token

For all dashboard and management API calls. Obtain a token by calling POST /api/login.php, then pass it in the Authorization header.

API Key (X-API-KEY)

Exclusively for the public POST /api/Prealert.php endpoint used by courier partners. Retrieve your key from Courier Settings in the dashboard.

​
JWT Bearer Token

Every request to a management or dashboard endpoint must carry a valid Bearer token. Tokens expire after 8 hours, so your integration should re-authenticate when it receives a 401 response.

​
Obtain a token

Call POST /api/login.php with your credentials. The action field must be set to "login": 
{
  "action": "login",
  "username": "your_username",
  "password": "your_password"
}
A successful response returns: 
{
  "status": "success",
  "message": "Login successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "user": {
      "id": "42",
      "full_name": "Jane Smith",
      "username": "your_username",
      "role": "admin",
      "courier_id": null,
      "courier_code": null,
      "two_factor_enabled": false
    }
  },
  "timestamp": 1700000000
}

​
Use the token

Attach the data.access_token value to every subsequent request: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Code examples

curl -X POST https://your-domain/api/login.php \
  -H "Content-Type: application/json" \
  -d '{"action":"login","username":"your_username","password":"your_password"}'

# Then use the returned token:
curl https://your-domain/api/some-endpoint \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Two-Factor Authentication (2FA)

If your account has 2FA enabled, the standard login call does not return an access_token immediately. Instead, it returns an intermediate state that requires you to verify your TOTP code before receiving a usable token.

​
Step 1 — Initiate login

Send the same POST /api/login.php request with your username and password. When 2FA is required, the response looks like this: 
{
  "status": "2fa_required",
  "message": "Two-factor authentication required.",
  "data": {
    "preauth_token": "pre_eyJhbGciOiJIUzI1NiJ9..."
  },
  "timestamp": 1700000000
}

​
Step 2 — Verify your TOTP code

Send a second POST /api/login.php with the verify_2fa action, including the preauth_token from Step 1 and the six-digit code from your authenticator app: 
{
  "action": "verify_2fa",
  "preauth_token": "pre_eyJhbGciOiJIUzI1NiJ9...",
  "code": "123456"
}
A successful verification returns the standard token response: 
{
  "status": "success",
  "message": "Login successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "user": {
      "id": "42",
      "full_name": "Jane Smith",
      "username": "your_username",
      "role": "admin",
      "courier_id": null,
      "courier_code": null,
      "two_factor_enabled": true
    }
  },
  "timestamp": 1700000000
}
The preauth_token is short-lived (valid for 5 minutes) and single-use. If verification fails, the token is invalidated and you must restart the login flow from Step 1.

​
API Keys (Courier Partners)

Courier partner API keys grant access to a single endpoint: POST /api/Prealert.php. They do not grant access to any other part of the Shiipp API.

​
Obtain your API key

  1. Log in to the Shiipp dashboard.
  2. Go to Settings → Courier Settings.
  3. Copy the value displayed under API Key.

​
Pass the key in requests

Never embed your API key in client-side code, mobile app binaries, or public repositories. If your key is compromised, regenerate it immediately from the Courier Settings page — the old key is invalidated the moment a new one is generated.

​
Regenerate a key

Navigate to Settings → Courier Settings and click Regenerate API Key. Confirm the action in the dialog. Update all integrations with the new key before the page is closed, as the previous key stops working immediately.

​
Authentication Error Reference

The table below covers the HTTP status codes returned when authentication fails.
Status CodeMeaning
401Missing or invalid token / API key. Re-authenticate to obtain fresh credentials.
403Credentials are valid but the account is disabled or lacks permission for the requested resource. Contact your Shiipp administrator.
405Wrong HTTP method used on the endpoint (for example, GET instead of POST). Check the method in your request.