> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aeoral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Shiipp in Minutes

> Learn how to log in, obtain your credentials, and make your first API call to Shiipp — the logistics and warehouse management platform.

Shiipp gives you two authentication paths depending on your role: courier partners authenticate using a dedicated API key scoped to the public Prealert endpoint, while all other API calls use a short-lived JWT Bearer token obtained from the login endpoint. Follow the steps below to go from zero to your first successful API call.

<Note>
  Your Shiipp base URL (for example, `https://acme.shiipp.com`) is provisioned by your Shiipp administrator. Replace `https://your-domain` in every example below with the URL they provide.
</Note>

<Steps>
  <Step title="Log in and obtain your Bearer token">
    Send a `POST` request to `/api/login.php` with your Shiipp credentials. Include `"action": "login"` along with your username and password. On success, the response contains an `access_token` you will use for all subsequent requests.

    **Request**

    ```json theme={null}
    POST https://your-domain/api/login.php
    Content-Type: application/json

    {
      "action": "login",
      "username": "youruser",
      "password": "yourpassword"
    }
    ```

    **Response**

    ```json theme={null}
    {
      "status": "success",
      "message": "Login successful",
      "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "user": {
          "id": "42",
          "full_name": "Jane Smith",
          "username": "youruser",
          "role": "admin",
          "courier_id": null,
          "courier_code": null,
          "two_factor_enabled": false
        }
      },
      "timestamp": 1700000000
    }
    ```

    Copy the value of `data.access_token` — you will need it in the next step.
  </Step>

  <Step title="Attach the token to every API request">
    Pass the token in the `Authorization` header on all subsequent calls to the Shiipp API.

    ```http theme={null}
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    ```

    Tokens are valid for **8 hours**. After expiry, repeat Step 1 to obtain a fresh token. Your application should handle `401 Unauthorized` responses by re-authenticating automatically.
  </Step>

  <Step title="Courier partners: locate your API key">
    If you are a courier partner, you have a separate API key that grants access to the public Prealert endpoint. You do not need a JWT token for this endpoint.

    1. Log in to the Shiipp dashboard.
    2. Navigate to **Settings → Courier Settings**.
    3. Copy the value shown under **API Key**.

    Pass this key in every Prealert request using the `X-API-KEY` header:

    ```http theme={null}
    X-API-KEY: your_api_key_here
    ```
  </Step>

  <Step title="Submit your first prealert">
    With your API key in hand, submit a prealert by posting shipment details to `/api/Prealert.php`. `UserCode` and `TrackingNumber` are required; `Vendor`, `Description`, and `Reference` are optional.

    **Request**

    ```json theme={null}
    POST https://your-domain/api/Prealert.php
    X-API-KEY: your_api_key_here
    Content-Type: application/json

    {
      "UserCode": "CUST001",
      "TrackingNumber": "1Z9999999999999999",
      "Vendor": "Amazon",
      "Description": "Electronics",
      "Reference": "ORD-2024-001"
    }
    ```

    **Success response** (HTTP 201)

    ```json theme={null}
    {
      "status": "success",
      "message": "Pre-alert logged successfully",
      "data": {
        "prealert_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
    ```

    Store the returned `prealert_id` to track and reference this shipment in future API calls.
  </Step>
</Steps>

<Tip>
  Ready to go deeper with courier integrations? See the [Courier Overview](/courier/overview) for the full list of endpoints, field definitions, and webhook configuration.
</Tip>