Common Request Headers

YMS is a multi-tenant system. Each tenant may have multiple yards, and the finest level of data isolation is at the yard level. All API requests must include the following common headers to ensure proper tenant isolation and data handling.

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the login API. Use the `accessToken` value from the login response. Example: `Bearer eyJraWQi...`
`X-Tenant-Id`	Yes	Tenant identifier. Determines which tenant's data to access. Obtained from the login response `userProfile.tenantId`.
`X-Yard-Id`	Yes	Yard identifier. The finest level of data isolation. A tenant may have multiple yards; this header specifies which yard's data to operate on. Obtained from the login response `userProfile.yardList[].yardId`.
`Item-Time-Zone`	Yes	Timezone identifier (e.g., `America/Los_Angeles`, `Asia/Shanghai`). Used for time conversion between your local time and the system's stored timestamps.

How to Obtain These Values

Step 1: Login

Call the login API to obtain your access token and user profile:

POST /auth/yms/login-by-password

Request Body:

{
  "username": "your_username",
  "password": "your_password",
  "tenantId": "your_tenant_id"
}

Response (key fields):

{
  "code": 0,
  "msg": "OK",
  "success": true,
  "data": {
    "accessToken": "eyJraWQi...",
    "userProfile": {
      "userId": "1827886404912771075",
      "userName": "your_name",
      "tenantId": "LLUI0001",
      "yardList": [
        {
          "yardId": "LLUI0001_YARD-1",
          "yardName": "West Coast Warehouse #2",
          "timezone": "America/Los_Angeles"
        }
      ],
      "defaultYardId": "LLUI0001_YARD-1"
    }
  }
}

Step 2: Extract Header Values

From the login response, extract:

Authorization: Bearer + data.accessToken
X-Tenant-Id: data.userProfile.tenantId
X-Yard-Id: Choose from data.userProfile.yardList[].yardId (or use data.userProfile.defaultYardId)
Item-Time-Zone: Use the timezone value from the corresponding yard in data.userProfile.yardList[]

Example Request

POST /public/receipt/create HTTP/1.1
Host: yms-staging.item.com
Authorization: Bearer eyJraWQi...
X-Tenant-Id: LLUI0001
X-Yard-Id: LLUI0001_YARD-1
Item-Time-Zone: America/Los_Angeles
Content-Type: application/json
 
{
  ...
}

Timezone Handling

YMS stores all time values as timestamps (epoch milliseconds) in the database. The Item-Time-Zone header controls how times are interpreted:

On write: Time values in your request (e.g., 2026-05-24T23:50:21) are interpreted in the timezone specified by Item-Time-Zone and converted to a timestamp for storage.
On read: Stored timestamps are converted back to the timezone specified by Item-Time-Zone before being returned in the response.

Time format: All time fields in requests and responses use the format yyyy-MM-ddTHH:mm:ss (e.g., 2026-05-24T23:50:21).

Important: Always pass the correct timezone for the yard you are operating on. Using an incorrect timezone will result in time values being shifted. Each yard's timezone is available in the login response under yardList[].timezone.

Data Isolation Model

Tenant (X-Tenant-Id)
├── Yard A (X-Yard-Id)
│   ├── Receipts
│   ├── Loads
│   ├── Orders
│   └── ...
├── Yard B (X-Yard-Id)
│   ├── Receipts
│   ├── Loads
│   ├── Orders
│   └── ...
└── ...

Each API request operates within the scope of a single yard. Data from one yard is not accessible when querying another yard. Ensure you set X-Yard-Id to the correct yard for your operation.

Get Authorization External WMS Integration Guide