管理 API キー

管理 API キーを使用して、注文システムからライセンスを自動的に発行するか、サーバーからライセンスデータを読み取ります。これはベンダーのワークスペースを表します。

クライアントはどのキーを必要としていますか?

認証情報	誰が受け取るのか	何のためにあるのか
`lv_api_…` 管理 API キー	あなた自身のサーバー	製品、ポリシー、ライセンスを作成します。デバイス、使用状況、監査ログを表示する
`lv_lic_…` ライセンスキー	お客様のアプリケーション	デバイスのアクティブ化、検証、ハートビートの送信、およびリリース
製品公開鍵	クライアントに同梱可能	サーバーのライセンス署名を確認する

顧客ソフトウェアのライセンスチェックの場合は、ライセンスキーで十分です。管理 API キーはワークスペース全体を制御できます。顧客のソフトウェアや公開ページには決して埋め込まないでください。

キーを作成する

ワークスペースの所有者としてサインインして開きます API Keyをクリックし、「API キーの作成」をクリックします。
「オーダーシステム」など、目的に応じた名前を付けます。クエリの場合は読み取り専用を選択し、ライセンスを作成または変更する場合は読み取り/書き込みを選択します。有効期間は 1 ～ 365 日です。
保存後すぐに完全なキーをコピーします。一度だけ表示されます。プライベートサーバー設定または環境変数に保存します。

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

この例は製品一覧を取得します。サーバー URL を設定する変数： LICENTIVO_URL 。作成した完全な管理キーを設定する変数： LICENTIVO_API_KEY 。設定後に実行してください。

curl "$LICENTIVO_URL/api/v1/products?limit=25" \
  -H "Authorization: Bearer $LICENTIVO_API_KEY"

この構文は Bash/macOS/Linux 用です。 Windows PowerShell で、次を使用します。 curl.exe;環境変数は $env:LICENTIVO_URL と $env:LICENTIVO_API_KEY。 9 言語すべてでの完全なリクエストの例も次のとおりです。サーバー管理 API SDK ページのキーオプション。

成功すると、HTTP 200 が返されます。 data.items。 Bearer Key 管理リクエストには、ログイン Cookie も CSRF トークンも必要ありません。

権限と失効

読み取り専用キーはリソースを表示できます。読み取り/書き込みキーを使用して、製品、ポリシー、ライセンスを作成および変更することもできます。管理キーではアカウント、チーム、システム設定、支払いを管理できません。これらには、承認されたアカウントでのログインが必要です。

漏えいしたキーや使わなくなったキーはコンソールで失効させます。差し替える場合は「ローテーション」を選んでください。古いキーは直ちに無効になるため、サーバー側の設定を新しいキーへ更新します。

プランの API 利用枠に計上されるのは、認証、検証、ハートビート、端末解除のリクエストです。これらの管理 API リクエストは、その利用枠には計上されません。

一般的なリクエストとレスポンスの規則

アイテム	共通ルール
サーバーのオリジン	`LICENTIVO_URL` はライセンスサーバーのオリジンです。 API パスは次で始まります `/api/v1` 。
認証	`Authorization: Bearer YOUR_MANAGEMENT_API_KEY`。読み取り専用キーの使用 `scope=read`;読み取り/書き込みキーの使用 `scope=write`。キーは独自のワークスペースにアクセスします。書き込みには、その作成者がアクティブな所有者である必要もあります。
JSONボディ	本文付きのリクエストの場合は、送信してください。 `Content-Type: application/json`。ボディは 64 KiB に制限されています。不明なフィールド、複数の JSON オブジェクト、および無効な型は拒否されます。マークされた操作 `{}` 空の JSON オブジェクトが必要です。 GET と DELETE には本体がありません。
アップデート	PATCH は、省略されたフィールドを保持します。基本的な更新には、少なくとも 1 つの編集可能なフィールドが必要です。条件付き要件を参照してください。 `duration_days`。
成功と失敗	成功した JSON 応答では、 `{"data": ..., "request_id": "..."}`;エラー使用 `{"error": {"code": "...", "message": "..."}, "request_id": "..."}`。通常、作成は 201 を返し、読み取りと更新は 200、キューに入れられたタスクは 202 を返します。
ファイル応答	成功した CSV および ZIP 応答には、 `data` ラッパー。エラーには引き続き JSON が使用されます。の `X-Request-ID` 応答ヘッダーはリクエストを識別します。
ページネーション	ページ分割された操作のデフォルトは `limit=25`、`offset=0`;範囲は 1 ～ 100 および 0 ～ 100000 です。ほとんどのリストは返されます `items` と `total`、ページングパラメータがエコーされるかどうかは、インターフェイスフィールドテーブルに従うものとします。監査レコードは total を返しません。次のページでは offset が追加され、limit 未満になると停止します。リストされていないフィルターパラメーターは信頼しないでください。
日付とお金	日時文字列は UTC / RFC 3339 形式です。オフライン申請では、次の値を Unix 秒で指定します： `created_at` 。金額のフィールドで末尾が `_cents` のものは通貨単位の 100 分の 1、`_micros` のものは 100 万分の 1 です。通貨は次の値で確認します： `currency` 。

再試行とべき等性

通常の作成、更新、キーローテーションには、共通の重複排除機能はありません： Idempotency-Key 。タイムアウト後に無条件で再送すると、発行や更新が二重に行われる可能性があります。確実な注文処理には、次の API を使います： POST /api/v1/licenses/batch。注文ごとに本文へ指定する ID を生成・保存します： request_id。再試行では元の ID と同一の内容を使ってください。オンボーディングも本文の request_id で重複を排除します。

トップレベルの応答 request_id ビジネス冪等性 ID とは異なります。サーバーは HTTP リクエストごとに前者を生成しますが、後者はビジネス操作ごとに保持します。 202 以降のタスクのステータスをポーリングします。429 では、次に従って待機します。 Retry-After 。 5xx または接続が失われた場合、書き込み結果が不確実になる可能性があります。最初にクエリを実行するか、その操作の冪等性ルールを使用して回復します。

管理エラーとリカバリ

HTTP / error.code	原因と回復方法
`400 INVALID_INPUT` `415 JSON_REQUIRED`	再試行する前に、フィールド、条件要件、または Content-Type を修正してください。
`401 UNAUTHENTICATED`	キーの形式が不正であるか、期限切れまたは取り消されているか、そのアカウント/ワークスペースが非アクティブです。完全なキーとアカウントの状態を確認します。
`403 FORBIDDEN` `403 CSRF_INVALID`	scope、Owner のロールとログインセッションの要件を確認してください。 Cookie 書き込み操作 CSRF Token は現在のセッションと一致する必要があります。
`404 NOT_FOUND` `405 METHOD_NOT_ALLOWED`	リソース ID、ワークスペース、アーカイブ状態、および HTTP メソッドを確認します。 405 応答には、Allow に許可されたメソッドがリストされます。
`409 PRODUCT_DISABLED` `409 RESOURCE_IN_USE`	まず製品を有効にしてください。製品またはポリシーをアーカイブする前に、依存リソースを解決します。
`409 LICENSE_REVOKED` `409 PERPETUAL_LICENSE`	取り消されたライセンスは復元または更新できません。永久ライセンスには、使用期限を延長する必要はありません。
`409 DEVICE_LIMIT_BELOW_ACTIVE` `409 ACTIVE_DEVICES_CONFLICT`	制限を引き下げたり、ライセンスモデルを切り替えたりする前に、過剰なデバイス/セッションを解放してください。
`409 POLICY_CHANGED` `409 PREVIEW_STALE`	ポリシーリビジョンをリロードするか、送信する前に変更を再度プレビューします。同時更新を保持します。
`409 IDEMPOTENCY_CONFLICT`	ビジネス request_id は別のコンテンツで再利用されました。再試行では、元の ID と本文が保持されます。新しい操作には新しい ID が必要です。
`409 KEY_LIMIT` `409 KEY_INACTIVE`	アクティブなキーは最大 100 個まで許可されます。未使用のキーを取り消します。ローテーションには、作成者がアクティブな所有者のままであるアクティブなキーが必要です。
`409 PLAN_VERSION_CONFLICT` `409 INVOICE_STATE_CONFLICT` `409 JOB_STATE_CONFLICT`	操作する前に、価格、請求書、またはタスクのステータスを再読み取りします。 failed の請求タスクのみが再試行できます。
`409 DELIVERY_RUNNING` `409 WEBHOOK_DISABLED`	実行中の配信を待つか、最初にエンドポイントを有効にしてください。受信者はイベント ID によって重複を排除する必要があります。
`413 EXPORT_TOO_LARGE` `429 RATE_LIMITED`	フィルターは最大 5000 行までエクスポートするか、ページネーションを使用します。レートが制限されている場合は、Retry-After に従って待機します。
`500 INTERNAL_ERROR` `503 DEFAULT_PLAN_DISABLED`	診断のために request_id を保持します。デフォルトの許可が無効になっている場合は、管理者に問い合わせてください。オペレーションの冪等性ルールに従って、不確実な書き込みを回復します。

オフライン操作では、ランタイムライセンスエラーが返される場合もあります。参照してくださいトラブルシューティングとライセンスのエラー。

専門用語

用語	意味
`authentication / authorization`	認証/認可: 認証情報の ID を確立し、操作の許可を確認します。
`scope`	scope はキーの権限範囲です。read は読み取り、write は読み書きを許可します。アカウントの owner / read_only ロールとは別のものです。
`policy / plan / purchase`	ライセンスポリシー/料金プラン/パッケージ購入契約: それぞれ、ソフトウェアライセンスルール、サービス価格、購入した権利。
`license / license key`	ライセンス / ライセンスキー: それぞれ管理記録と顧客のアクティベーションシークレット。どちらも管理 API キーとは異なります。
`activation / seat / lease`	アクティベーション / シート / 認証リース: それぞれ、デバイスまたはセッションレコード、同時使用スロット、および期限付きのサーバー署名付き認証。
`revoke / suspend / archive / release`	取り消し/一時停止/アーカイブ/リリース: 取り消しは最終的なもので、一時停止は元に戻すことができ、アーカイブすると通常の可視性が失われ、リリースするとデバイスまたはシートが解放されます。
`rotate / idempotency / reservation`	ローテーション / 冪等性 / 予約: キーを置き換え、同じ操作を繰り返し実行することによる追加の影響を防止し、コミットする前に機能の使用を予約します。

すべての管理リクエストと応答

Bearer キーで呼び出すすべての操作と、オーナーのログインセッションで行うキーの作成・一覧取得・ローテーション・失効を掲載しています。操作を選ぶと、呼び出し方、応答、フィールド、条件を確認できます。例の認証情報はすべて説明用です。

API リファレンスを読み込み中…

管理キーの権限

読み取り専用キーは「read または write キー」の操作を呼び出せます。write キーは「write キー」の操作も呼び出せます。キーの管理、アカウント、メンバー、システム設定、決済、返金には、権限を持つログインセッションが必要です。月次請求の照会と処理には、各操作に記載した権限を使います。顧客アプリの実行時操作では顧客の認証情報を使います。詳細： SDK ライセンス呼び出し。

機械可読ファイルをダウンロードする OpenAPI JSON（現在の言語）Postman などのツールにインポートするため。 Web フィールドの説明はドキュメントの言語に従っています。