API クイックスタート

Developer Hub でサービスアカウントと API キーを作成し、最初のリクエストを送信します。このクイックスタートでは API キー認証を使用するため、OAuth クライアントは必要ありません。連携で有効期間の短い OAuth アクセストークンが必要な場合は、認証を参照してください。

前提条件

Living Security ダッシュボードへの管理者アクセス権。
設定 → Integrations & Developers → Developer Hub に Developer Hub が表示されていること。

認証情報の作成

サービスアカウントを作成する

Developer Hub で Service accounts タブを開き、アカウントを作成します。わかりやすい名前(例: reporting-pipeline)を付け、そのキーで使用できる権限を付与します。このガイドでは organization:read で十分です。アカウントの権限は、そのアカウントの下で作成されるすべてのキーの上限となります。キーがサービスアカウントで許可されている範囲を超える操作を行うことはできません。

API キーを作成する

サービスアカウントの詳細ページを開き、キーを作成します。このキーに必要な権限(アカウントの権限の一部)と有効期限を選択します。有効期限は 30 日、90 日、365 日、またはカスタム期間から選択できます。有効期限の設定は必須です。キーのシークレットは lsk_live_ で始まり、一度だけ表示されます。すぐにシークレットマネージャーにコピーしてください。後から取得することはできません。

API キーのシークレットをバージョン管理にコミットしたり、クライアント側のコードに埋め込んだりしないでください。シークレットを保持している人は誰でも、そのキーの権限で操作を実行できます。

リージョンを選択する

組織のデータレジデンシーに一致するリージョンの /v1 ホストを呼び出します。キーは、そのホストでのみ認証されます。

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

どのホストを使用すべきかわからない場合は、リージョンを参照してください。有効なキーを別のリージョンに送信すると、unauthorized として失敗します。ホストを切り替えるには、下のサンプルにあるリージョンのドロップダウンを使用してください。

最初のリクエストを送信する

LIVING_SECURITY_API_KEY をシークレットマネージャーから、リクエストを実行するプロセスの環境に読み込みます。以下の例では、ソースコードにシークレットを埋め込まずに読み取ります。Python の場合は、先に requests をインストールしてください。シークレットを HTTP Basic 認証のパスワードフィールドまたはユーザー名フィールドに指定して API を呼び出します。どちらでも機能するため、両方のフィールドの入力が必要なクライアント(Power BI の Web コネクタなど)では、もう一方のフィールドに apikey のようなプレースホルダーを指定できます。

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

成功すると、次のように組織情報が返されます。

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

このレスポンスが返された場合、認証情報は有効です。このリクエストは、Developer Hub の Request logs タブにもまもなく表示されます。

同じシークレットを使用した Bearer 認証(Authorization: Bearer lsk_live_...)も使用できます。Basic 認証は、Power BI の Web コネクタのように、ユーザー名とパスワードのみに対応するツールから接続できるようにするために用意されています。

認証の仕組み

認証情報によって組織が決まります。 /v1 のリクエストにはテナントを指定する要素がなく、組織のパスセグメントも組織ヘッダーもありません。x-organization-id ヘッダーを送信すると、invalid_request で拒否されます。ホストは、その組織のリージョンと一致している必要があります。リージョンを参照してください。
権限は操作ごとに確認されます。 各 /v1 操作には、指定された権限が必要です(例: GET /v1/organization には organization:read が必要です)。権限のないキーには、コード insufficient_permission の 403 が返されます。
キーには有効期限があり、ダウンタイムなしでローテーションできます。 重複期間を設けたローテーションについては、API キーを参照してください。

エラーレスポンスの読み方

すべての /v1 エラーは、安定したマシンコードを持つ application/problem+json(RFC 9457)です。たとえば、認証情報がない、または不明なリクエストでは、次のレスポンスが返されます。

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

処理の分岐には code を使用し、detail は使用しないでください。解決手順は doc_url に従い、サポートに問い合わせる際は request_id を含めてください。これは Request-Id レスポンスヘッダーおよび Developer Hub のリクエストログと一致します。すべてのコードはエラーリファレンスに掲載されています。

コントラクトバージョン

すべてのレスポンスでは、処理に使用されたコントラクトバージョンが Living-Security-Version ヘッダーに返され、相関用の Request-Id ヘッダーも併せて返されます。日付を指定して、リクエストを公開済みのコントラクトバージョンに固定できます。

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

バージョンは次の順序で解決されます。リクエストヘッダーがある場合はそれが優先され、ない場合はサービスアカウントに固定されたデフォルト、それもない場合は公開されている最新バージョンが使用されます。公開されていない(または提供終了日を過ぎた)バージョンを指定すると、コード unsupported_version の 400 が返されます。公開済みのバージョンとその変更内容は、API 変更履歴に記載されています。

最初のリクエストのトラブルシューティング

結果	次のアクション
`401 unauthorized`	シークレット、その有効期限、および組織のリージョンを確認してください。有効な認証情報を使用して他のホストを試さないでください。
`403 insufficient_permission`	サービスアカウントとそのキーの両方に `organization:read` を付与してください。
`400 unsupported_version`	変更履歴から公開済みのバージョンを選択してください。
`429 rate_limited`	`Retry-After` まで待機し、制限付きリトライの例に従ってください。
ネットワークタイムアウト	接続状況を確認し、アプリケーションのリトライ予算の範囲内でこの読み取りを再試行してください。

その他のエラーについては、レスポンスの doc_url に従ってください。サポート用に Request-Id を保管してください。サポートチケットには、Authorization ヘッダーや API キーを含めないでください。

次のステップ

リージョン

組織に合わせて、US または EU の /v1 ホストを選択します。

ページネーション

page_token とリストエンベロープを使用して、リストを順に取得します。

レート制限

リクエストの予算を理解し、429 レスポンスを処理します。

エラーリファレンス

すべてのエラーコード、その HTTP ステータス、および解決方法を確認できます。

Developer Hub

サービスアカウント、API キー、リクエストログを管理します。

デベロッパーハブ

パブリックAPI v1

API v1リファレンス

前提条件

認証情報の作成

認証の仕組み

エラーレスポンスの読み方

コントラクトバージョン

最初のリクエストのトラブルシューティング

次のステップ

リージョン

ページネーション

レート制限

エラーリファレンス

Developer Hub

デベロッパーハブ

パブリックAPI v1

API v1リファレンス

​前提条件

​認証情報の作成

​認証の仕組み

​エラーレスポンスの読み方

​コントラクトバージョン

​最初のリクエストのトラブルシューティング

​次のステップ

リージョン

ページネーション

レート制限

エラーリファレンス

Developer Hub

前提条件

認証情報の作成

認証の仕組み

エラーレスポンスの読み方

コントラクトバージョン

最初のリクエストのトラブルシューティング

次のステップ