> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/getting-started/authentication.md).

# 認証

公開 API の認証は 2 系統です。外部システム（EC・POS・WMS・基幹）からのデータ push / routing / 設定は **ingest API キー**（`x-ingest-secret`）、倉庫スタッフのピッキングアプリ（picking-ios）からの `/api/operator/*` は **operator JWT**（`Authorization: Bearer`）で認証します。

> **Base URL** `https://api.lmile.io`

* **ほとんどの公開 API**（Ingestion / Routing / Fulfillment / Oversell / Customer Orders / Configuration / Webhooks）は **ingest API キー** で認証します（下記「Ingest API キー認証」）。
* **倉庫スタッフ向けの** [**Operator API**](/lmile-docs/operator-api/login.md)（`/api/operator/*`）は **operator JWT** で認証します（下記「Operator JWT 認証」）。read 系（照会）は JWT のみ、棚ピック（`/api/operator/shelf/pick`）と確保スキャン（`/api/operator/secure-scan`）は機械間連携も想定し `x-ingest-secret` でも呼べます。
* [Routing](/lmile-docs/routing-api/orders.md) の一部 write（在庫確保 / 売越し / 再引き当て / 売越しケース）は **どちらの系統でも**呼べます（下記「Routing write の 2 系統認証」）。

## Ingest API キー認証

## Headers

```http
x-ingest-secret: {API_KEY}
Content-Type: application/json
```

| Header            | Required | 説明                  |
| ----------------- | :------: | ------------------- |
| `x-ingest-secret` |     ✓    | 発行された ingest API キー |
| `Content-Type`    |     ✓    | `application/json`  |

* **`shop` は省略できます**（キーが 1 つのアカウントにひも付いている場合。下記「shop スコープ」）。
* 認証に失敗すると `401 unauthorized`、シークレット未設定のサーバーは `503` を返します。

## shop スコープ

発行される API キーは、あなたのアカウント（`shop`）に**ひも付いています**。`shop` は LastMile 上のアカウントの識別子です。Shopify を使わない連携（POS・WMS・基幹システムなど）でも同じ値です。

* キーが 1 つのアカウントにひも付いている場合、`shop` は**送らなくてかまいません**。送らなければ、キーのアカウントとして処理します。
* 各エンドポイントの例には `shop` が入っていますが、そのまま送っても省略しても結果は同じです。
* `shop` を送る場合は、キーにひも付くアカウントと一致させてください。一致しない場合は `403 shop not authorized for this key` を返します。
* 複数のアカウントにひも付くキーでは、どのアカウントか決められません。`shop` を必ず送ってください。
* 1 つのキーで、ひも付いた範囲のすべての ingest / routing エンドポイントを利用できます。

たとえば次の 2 つは同じ結果になります。

```http
GET https://api.lmile.io/api/ingest/accessory-services
x-ingest-secret: {API_KEY}
```

```http
GET https://api.lmile.io/api/ingest/accessory-services?shop=demo-store.myshopify.com
x-ingest-secret: {API_KEY}
```

## API キーの取得

キーは Last Mile のコンソール（[設定 > API キー](https://lmile.io/mypage/settings/api-keys)）で発行します。発行・失効ができるのは、組織のオーナー・管理者です。

1. 何に使うキーか分かる名前（例: 基幹システムの在庫連携）を付けて発行します。
2. **キーは発行したときに 1 回だけ表示されます。** 再表示はできないので、その場でコピーして安全な場所に保管してください。
3. 使わなくなったキーは同じ画面で失効します。失効したキーで呼ぶと `401 unauthorized` を返します。

キーを紛失した場合は、新しいキーを発行して連携先を切り替えてから、古いキーを失効してください（先に失効すると連携が止まります）。複数のアカウントにまたがるキーが必要な場合は <admin@lmile.io> へご連絡ください。

## 取り扱いルール

* サーバーサイド環境変数に格納する
* ブラウザ JS / フロントエンドに埋め込まない
* Git にコミットしない

```env
INGEST_SECRET=lmik_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Operator JWT 認証

倉庫スタッフ向けのピッキングアプリ（picking-ios）が呼ぶ [Operator API](/lmile-docs/operator-api/login.md)（`/api/operator/*`）専用の認証系統です。ingest API キー（機械間 secret）とは独立しており、スタッフ個人のログインで発行された JWT を使います。

> 個人ログインの認証情報は機械間の `x-ingest-secret` とは別物です。倉庫スタッフは ingest API キーを持たず、operator JWT だけで `/api/operator/*` を利用します。

### Headers

```http
Authorization: Bearer {OPERATOR_JWT}
Content-Type: application/json
```

| Header          | Required | 説明                                                                                       |
| --------------- | :------: | ---------------------------------------------------------------------------------------- |
| `Authorization` |     ✓    | `Bearer {OPERATOR_JWT}`（[Operator Login](/lmile-docs/operator-api/login.md) で取得した `jwt`） |

### トークンの取得

* スタッフのアカウントはプラットフォーム / 管理者側で発行します（アプリ内のセルフサインアップはありません）。
* JWT は [`POST /api/operator/login`](/lmile-docs/operator-api/login.md)（`email` + `password`）、[`POST /api/operator/login/google`](/lmile-docs/operator-api/login.md)（Google サインインの `idToken`）、または [`POST /api/operator/login/apple`](/lmile-docs/operator-api/login.md)（Sign in with Apple の `identityToken`）で発行し、有効期限が切れたら [`POST /api/operator/refresh`](/lmile-docs/operator-api/login.md)（`refreshToken`）で更新します。
* 各スタッフがどの `shop` を操作できるかの束縛は Last Mile が割り当てます（発行されたばかりで未割当のアカウントは未束縛です。割当・失効は <admin@lmile.io> へご連絡ください）。

### shop スコープ（staff↔shop 束縛）

operator JWT は、そのスタッフに束縛された `shop` だけを操作できます。

* 各エンドポイントが受け取る `shop`（read 系は query、write 系はボディ）が束縛 shop に含まれない場合、`403 shop_not_authorized` を返します。
* トークンが無い / 不正・失効している場合は `401`（`missing_token` / `invalid_token`）です。

## Routing write の 2 系統認証

[出荷ステータス遷移](/lmile-docs/fulfillment-api/fulfillment.md)（`/api/routing/fulfillment`）・[在庫確保](/lmile-docs/fulfillment-api/units.md)（`/api/routing/secure`）・[確保スキャン](/lmile-docs/operator-api/secure-scan.md)（`/api/operator/secure-scan`）・[売越しマーク / 再引き当て](/lmile-docs/oversell-api/oversell-reallocate.md)（`/api/routing/oversell` / `/api/routing/reallocate`）・[売越しケース](/lmile-docs/oversell-api/cases.md)（`/api/routing/oversell-case`）・[宛先住所修正 / ラベル再発行](/lmile-docs/fulfillment-api/address-recovery.md)（`/api/routing/shipment/address` / `/api/routing/shipment/retry-label`）・[ラベル手動再印刷](/lmile-docs/fulfillment-api/print-label.md)（`/api/routing/shipment/print-label`）・[MFC 棚付き入庫](/lmile-docs/ingestion-api/mfc-inventory.md)（`/api/ingest/mfc-inventory`）・[出荷元変更](/lmile-docs/oversell-api/source-change.md)（`/api/routing/change-source`）の 11 エンドポイントは、**ingest API キー（`x-ingest-secret`）と operator JWT（`Authorization: Bearer`）のどちらでも**呼べます。

* 系統は**ヘッダの有無で明示判別**します（フォールバックはしません）。`x-ingest-secret` を付けると ingest 系統、付けず `Authorization` を付けると operator 系統で検証します。
* 既存の機械間クライアント（`x-ingest-secret` のみ提示）の挙動は不変です。
* operator JWT で呼んだ場合、その操作者（スタッフ）が更新レコードに記録されます。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lmile.gitbook.io/lmile-docs/getting-started/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.