Authenticate API Requests to Shiipp

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"

// Step 1: Authenticate
const loginRes = await fetch("https://your-domain/api/login.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "login",
    username: "your_username",
    password: "your_password",
  }),
});

const { data } = await loginRes.json();
const accessToken = data.access_token;

// Step 2: Call a protected endpoint
const res = await fetch("https://your-domain/api/some-endpoint", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

const result = await res.json();

<?php
// Step 1: Authenticate
$ch = curl_init("https://your-domain/api/login.php");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "action"   => "login",
        "username" => "your_username",
        "password" => "your_password",
    ]),
]);
$response    = json_decode(curl_exec($ch), true);
$accessToken = $response["data"]["access_token"];
curl_close($ch);

// Step 2: Call a protected endpoint
$ch = curl_init("https://your-domain/api/some-endpoint");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer {$accessToken}"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
?>

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. 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:

TOTP code
Backup code

{
  "action": "verify_2fa",
  "preauth_token": "pre_eyJhbGciOiJIUzI1NiJ9...",
  "code": "123456"
}

{
  "action": "verify_2fa",
  "preauth_token": "pre_eyJhbGciOiJIUzI1NiJ9...",
  "code": "ABCD-EFGH"
}

Use one of the backup codes generated when you first enabled 2FA. Each backup code is single-use and is invalidated immediately after it is consumed.

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

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

Pass the key in requests

HTTP header (recommended)
Query parameter (not recommended)

POST https://your-domain/api/Prealert.php
X-API-KEY: your_api_key_here
Content-Type: application/json

POST https://your-domain/api/Prealert.php?api_key=your_api_key_here
Content-Type: application/json

Passing the key as a query parameter can expose it in server access logs, browser history, and referrer headers. Use the X-API-KEY header whenever possible.

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 Code	Meaning
`401`	Missing or invalid token / API key. Re-authenticate to obtain fresh credentials.
`403`	Credentials are valid but the account is disabled or lacks permission for the requested resource. Contact your Shiipp administrator.
`405`	Wrong HTTP method used on the endpoint (for example, `GET` instead of `POST`). Check the method in your request.

Get Started

Core Concepts

Courier Integration

Guides

FAQ & Troubleshooting

Authenticate API Requests to Shiipp

JWT Bearer Token

API Key (X-API-KEY)

JWT Bearer Token

Obtain a token

Use the token

Code examples

Two-Factor Authentication (2FA)

Step 2 — Verify your TOTP code

API Keys (Courier Partners)

Obtain your API key

Pass the key in requests

Regenerate a key

Authentication Error Reference

JWT Bearer Token

API Key (X-API-KEY)

​JWT Bearer Token

​Obtain a token

​Use the token

​Code examples

​Two-Factor Authentication (2FA)

​Step 1 — Initiate login

​Step 2 — Verify your TOTP code

​API Keys (Courier Partners)

​Obtain your API key

​Pass the key in requests

​Regenerate a key

​Authentication Error Reference

JWT Bearer Token

Obtain a token

Use the token

Code examples

Two-Factor Authentication (2FA)

Step 1 — Initiate login

Step 2 — Verify your TOTP code

API Keys (Courier Partners)

Obtain your API key

Pass the key in requests

Regenerate a key

Authentication Error Reference