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

# レガシー Public API

> API アクセスキーをベアラートークンに交換する既存の /api/v1 連携を維持管理します。

このガイドでは、API アクセスキーをベアラートークンに交換する既存の `/api/v1` 連携について説明します。認証情報とリクエスト形式は、`/v1` Public API とは異なります。

新規に連携を構築する場合は、[API クイックスタート](/ja/developers/v1/quickstart)および[認証](/ja/developers/v1/authentication)から開始してください。新しい `/v1` API では、サービスアカウントの API キーまたは OAuth アクセストークンを使用します。

## 始める前に

次のものが必要です。

* API アクセスキーの管理を許可する Living Security へのアクセス権
* **設定 → Access Keys** で作成した API アクセスキー
* 認証情報の作成時に一度だけ表示されるアクセスキーシークレット
* Public API の認証情報とともに Living Security から提供される API 発行者 ID
* 連携対象の組織のリージョン別ベース URL
* サーバー側のランタイムとシークレットマネージャー

アクセスキーシークレットは、ブラウザーコード、モバイルアプリ、ソース管理、クライアント側の環境変数、チケット、共有ログに配置しないでください。

<Note>
  Access Keys ダイアログには一度だけ表示されるシークレットが表示されますが、API 発行者 ID は表示されません。Public API の認証情報とともに Living Security から発行者 ID が提供されていない場合は、[Living Security サポート](mailto:support@livingsecurity.com)にお問い合わせください。発行者 ID は、アクセスキー ID や組織 ID とは異なります。
</Note>

## リージョン別ホスト

レガシー仕様では、次のリージョン別の `/api/v1` 本番ホストを使用します。

| リージョン | ベース URL |
| - | - |
| US | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| EU | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Living Security の組織に割り当てられたリージョンを使用してください。認可エラーや可用性のエラーを回避するためにリージョンを切り替えないでください。

## レガシーリソース

| リソース | サポートされる操作 |
| - | - |
| **人** | 組織内の人の検索と、個人のメンバーシップの取得 |
| **API アクセスキー** | API アクセスキーの作成、一覧表示、ローテーション、失効 |

操作、パラメーター、リクエスト、レスポンス、スキーマの完全な一覧については、**Developers → Public API Reference** を参照してください。操作がそこに記載されていない場合、その操作は現在 Public API に含まれていません。

## 認証

Public API へのアクセスは 2 段階で行われます。

1. シークレットアクセスキーと API 発行者 ID を、有効期間の短いベアラートークンと組織 ID に交換します。
2. 各 API リクエストでベアラートークンと組織 ID を送信します。

必須のリクエストヘッダーは次のとおりです。

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

組織ヘッダーには、アクセスキーの交換で返された組織を指定する必要があります。キーによって、任意の組織 ID へのアクセスが認可されることはありません。

### TypeScript SDK

現在のメジャーバージョンをインストールします。

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

次に、キーを交換して SDK を構成します。

```typescript theme={null}
import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});
```

EU の組織には EU のベース URL を使用してください。SDK による交換は、サーバー側の Node.js ランタイムでの使用を想定しています。

### REST リクエストの直接送信

SDK を使用せずに交換を行う場合は、そのベアラートークンと組織 ID をすべてのリクエストで送信してください。

```bash theme={null}
curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"
```

ベアラートークンの有効期間は短く設定されています。ベアラートークンを恒久的な認証情報として保持するのではなく、新しいトークンが必要なときにアクセスキーを再度交換してください。

## アクセスキーのライフサイクル

* キーには、所有する連携または自動化の名前を付けてください。
* アクセスキーのフォームで提供される最小権限のスコープを選択してください。
* 一度だけ表示されるシークレットは、すぐに保管してください。作成後またはローテーション後は取得できません。
* キーのローテーションは **設定 → Access Keys** から行い、古い認証情報を失効させる前に新しいキーをデプロイしてください。
* 使用されなくなったキーや、シークレットが漏えいした可能性があるキーは失効させてください。
* 人以外の連携には、お客様の組織で利用可能な場合、サービスアカウントキーを使用してください。

## ページネーション

人の検索では、`limit`、`cursor`、`offset`、`includeTotal` パラメーターがサポートされています。順次取得する場合は、直前のレスポンスで返されたカーソルを使用することを推奨します。

* `limit` のデフォルトは 50 で、1–100 を指定できます。
* `cursor` は、前回のレスポンスの続きから取得します。
* `offset` は指定した件数のレコードをスキップします。デフォルトは 0 です。
* `includeTotal=true` は、フィルター適用後の正確な件数をリクエストします。件数が不要な場合は省略してください。

エンドポイントが返す `pagination` オブジェクトを読み取ってください。受信した行数から次のページを計算したり、個別にページネーションしたリクエストを組み合わせて部分的な結果を自分でソートしたりしないでください。

## エラー

ドキュメント化されている JSON エラーは、次の一般的な形式です。

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

`message` は、文字列または検証メッセージの配列になる場合があります。

| ステータス | 意味 | 対応 |
| - | - | - |
| `400` | パラメーターまたはリクエストボディが無効です | 指摘された検証エラーを修正してください |
| `401` | ベアラートークンがない、無効、または期限切れです | アクセスキーを再度交換し、1 回だけ再試行してください |
| `403` | 認証情報に権限または組織へのアクセス権がありません | キーのスコープと組織のコンテキストを確認してください |
| `404` | 認可された組織内にリソースが存在しません | リソース ID と組織を確認してください |
| `408` | リクエストがタイムアウトしました | 上限付き指数バックオフで再試行してください |
| `429` | レート制限に達しました | `Retry-After` が存在する場合は、少なくともその時間だけ待機してください |
| `5xx` | 一時的なサービス障害です | 安全な読み取り操作は、上限付き指数バックオフで再試行してください |

厳選された仕様では、現時点で、全体に共通する 1 つの数値のレート制限は公開されておらず、すべての操作でリクエスト ID のレスポンスヘッダーが返されることも保証されていません。サポートに問い合わせる際は、UTC の時刻、メソッド、パス、ステータス、およびサニタイズ済みのレスポンスボディを記録してください。

操作が冪等性を明示的に記載していない限り、作成、ローテーション、失効、削除の操作を自動的に再試行しないでください。ネットワーク障害で結果が不明な場合は、リソースの現在の状態を確認してください。

## 互換性と非推奨化

V1 は、デフォルトで追加的に進化します。クライアントは、未知のレスポンスフィールドを無視する必要があります。破壊的変更には、文書化された移行パスが必要です。非推奨の操作は、移行期間中、その理由、利用可能な場合は代替手段、および終了日とともにリファレンスに残ります。

SDK は互換性のあるメジャーバージョンに固定し、アップグレードする前にリリースノートを確認してください。スキーマの信頼できる情報源としては、ファーストパーティのアプリクライアントではなく、生成された Public API Reference を使用してください。

## Public API、MCP、Web アプリケーション

| サーフェス | 用途 | 互換性モデル |
| - | - | - |
| **Public API** | お客様のシステム、パートナー、外部の自動化 | 安定したバージョン管理対象のリソース |
| **MCP** | 権限が付与された AI ツールとのやり取り | ツール仕様とコンパクトな構造化出力 |
| **Web アプリケーション** | Living Security 製品での人による作業フロー | UI とともに変更される可能性があるアプリ所有の仕様 |

AI ツールを Living Security に接続するには、[MCP 連携](/ja/integrations/mcp)を参照してください。

## サポート

次の情報を添えて、[Living Security サポート](mailto:support@livingsecurity.com)にお問い合わせください。

* 組織とリージョン
* 使用している場合は SDK の名前とバージョン
* UTC のタイムスタンプ、メソッド、パス
* HTTP ステータスとサニタイズ済みのエラーボディ

アクセスキーシークレット、ベアラートークン、お客様の非公開データは、決して含めないでください。

## 関連情報

<CardGroup cols={2}>
  <Card title="API アクセスキー" icon="key" href="/ja/integrations/api-keys">
    API 認証情報を作成、ローテーション、失効します。
  </Card>

  <Card title="MCP 連携" icon="robot" href="/ja/integrations/mcp">
    Model Context Protocol を通じて、サポートされている AI ツールを接続します。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.