レガシー Public API

このガイドでは、API アクセスキーをベアラートークンに交換する既存の /api/v1 連携について説明します。認証情報とリクエスト形式は、/v1 Public API とは異なります。新規に連携を構築する場合は、API クイックスタートおよび認証から開始してください。新しい /v1 API では、サービスアカウントの API キーまたは OAuth アクセストークンを使用します。

始める前に

次のものが必要です。

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

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

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

リージョン別ホスト

レガシー仕様では、次のリージョン別の /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 段階で行われます。

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

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

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

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

TypeScript SDK

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

npm install @livingsecurity/sdk@^1

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

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 をすべてのリクエストで送信してください。

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 エラーは、次の一般的な形式です。

{
  "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 連携を参照してください。

サポート

次の情報を添えて、Living Security サポートにお問い合わせください。

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

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

API アクセスキー

API 認証情報を作成、ローテーション、失効します。

MCP 連携

Model Context Protocol を通じて、サポートされている AI ツールを接続します。

パブリックAPI

パブリックAPIリファレンス

始める前に

リージョン別ホスト

レガシーリソース

認証

TypeScript SDK

REST リクエストの直接送信

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

ページネーション

エラー

互換性と非推奨化

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

サポート

関連情報

API アクセスキー

MCP 連携

パブリックAPI

パブリックAPIリファレンス

​始める前に

​リージョン別ホスト

​レガシーリソース

​認証

​TypeScript SDK

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

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

​ページネーション

​エラー

​互換性と非推奨化

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

​サポート

​関連情報

API アクセスキー

MCP 連携

始める前に

リージョン別ホスト

レガシーリソース

認証

TypeScript SDK

REST リクエストの直接送信

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

ページネーション

エラー

互換性と非推奨化

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

サポート

関連情報