作成¶
POST /api/v1/workspace/accesskey/add
概要¶
現在のワークスペースに API Key を作成し、読み取り/管理ロールをバインドします。
呼び出し前の準備と使用手順¶
現在のワークスペースで workspace.openAPIKeyManage 権限を持つ OpenAPI Key を使用します。ルート宣言には freeEdition バージョンの制限が記載されていますが、現在の OpenAPI 認証チェーンではそのバージョンチェックは実行されないため、バージョン自体が必ず 403 になるわけではありません。可用性はデプロイと実際の権限に基づいて確認してください。リソースのスコープは常にリクエストヘッダーの Key が属するワークスペースとなり、Body でワークスペースを切り替えることはできません。owner Key の場合は現在の識別情報に owner が含まれていることも必要で、インターフェースの管理権限だけではこのチェックを代替できません。
まずロール一覧から必要最小限のロールを選択し、次に既存の削除されていない Key の名前を確認してから、name、remark、および完全な roleUUIDs を送信します。roleUUIDs を省略するとデフォルトで ["wsAdmin"] になり、読み取り専用ではありません。明示的に [] を指定した場合はロール関連付けを書き込まないだけで、レスポンスは roleInfo=[] になります。現在の認証チェーンでは有効なロール関連付けがない場合でも ["wsAdmin"] にフォールバックするため、[] を使って権限ゼロの Key を作成したり権限を剥奪したりすることはできません。最小権限が必要な場合は、readOnly または確認済みのカスタムロールを明示的にバインドします。通常の分岐では、各ロールが現在のワークスペースで利用可能かつ status=0 であることを項目ごとに検証します。
過去の説明には owner を含まないと記載されていますが、現在の実装には owner 互換分岐があります。配列に owner を含めると owner Key のみを作成し、他のロールは無視して残りの要素を項目ごとに検証しません。現在の owner の識別情報が必要で、各ワークスペースにはシステム以外かつ削除されていない owner Key を 1 つだけ(無効化されたものを含む)許可します。owner を通常のロール配列に混在させないでください。
作成およびローテーションのレスポンスには ak/sk の平文が含まれるため、直ちに管理された認証情報ストレージに書き込みます。OpenAPI の認証ヘッダーには Key の値(たとえば返却された sk)を使用し、wsak_ で始まるリソース UUID は使用しないでください。後続の一覧/詳細は、呼び出し元の識別情報、対象が手動かバインド済みアカウントか、および現在の Key かどうかに影響され、マスクされる場合があります。後続の読み取りに頼って失われた認証情報を復元すべきではなく、現在のサービスの実装を「すべての識別情報で平文が二度と返されない」と説明することもできません。
この操作は冪等ではありません。同名によるエラーは古い Key を置き換えません。データベースへのコミットが成功してからレスポンスを返します。エラーやネットワーク中断の際は、まず一覧で名前と UUID を確認してから作成するかどうかを判断し、認証情報の重複を避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報です。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| roleUUIDs[*] | string | 単一の有効なロール UUID です。owner の識別情報のみが owner Key を作成できます。通常ロールの分岐では、未知/無効/クロスワークスペースのロールは拒否されます。 例: readOnly取得または入力方法: ロール一覧 が返す uuid を取得し、name は取得しません。 |
|
| name | string | Y | 必須文字列です。呼び出し元は空でない値にする必要がありますが、現在の宣言では非空を強制していません。格納列は 512 文字で、512 文字以下を推奨します。空白の自動除去は行いません。 null 許可: False 例: automation_reader取得または入力方法: 用途に応じて名前を定義し、API Key 一覧 で同名がないか確認します。 |
| remark | string | 省略可能な文字列で、最大 512 文字です。省略時は空文字列となり、null にはできません。 null 許可: False 最大長: 512 例: 仅读自动化取得または入力方法: 用途、担当者、更新方法を記録し、認証情報は保存しないでください。 |
|
| roleUUIDs | array | 省略可能な完全なロール UUID 配列です。省略時は ["wsAdmin"] です。[] は関連付けを書き込まないだけで、認証は引き続き wsAdmin にフォールバックするため、権限の剥奪には使用できません。各項目は文字列で指定します。null はサポートしません。owner を含む場合は特殊な互換分岐に入ります(使用説明を参照)。null 許可: False 例: ["readOnly"]取得または入力方法: ロール一覧 の content.data[].uuid から現在のワークスペースで利用可能なロールを取得します。組み込みの readOnly/wsAdmin/general もロール UUID です。 |
パラメータ補足説明¶
このエンドポイントは現在のワークスペースの手動 Key を作成します。必要なロールを明示的に設定してください。roleUUIDs を省略すると wsAdmin が使用されます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/accesskey/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"automation_reader","remark":"仅读自动化","roleUUIDs":["readOnly"]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | データベース番号です。新規作成のレスポンスはコミット前のスナップショットであるため null になる場合があります。後続の操作では uuid を使用します。 |
| content.uuid | string | wsak_ で始まる API Key リソース UUID で、詳細/削除/ローテーションのパスに使用します。DF-API-KEY の値ではありません。 |
| content.workspaceUUID | string | 現在の呼び出し Key が属するワークスペースの UUID です。 |
| content.name | string | Key の名前です。 |
| content.ak | string | 新しく生成された ak の平文です。リソース uuid ではなく、呼び出し先サービスの認証情報の取り決めに従って使用します。 |
| content.sk | string | 新しく生成された sk の平文で、OpenAPI の DF-API-KEY として使用できます。直ちに安全に保存し、ログには出力しないでください。 |
| content.accountUUID | string | バインドされたアカウントの UUID です。このエンドポイントで作成した場合は "" となり、アカウントバインドの認証情報は作成されません。 |
| content.createdWay | string | 作成元です。このエンドポイントの場合は manual です。 |
| content.businessType | string | 互換用の業務分類です。通常の手動 Key では空文字列です。 |
| content.isSystem | integer または boolean | システム組み込みのマーカーです。通常の手動 Key では 0/false です。 |
| content.isOwnerRole | integer または boolean | owner Key かどうかです。通常ロールで作成した場合は 0、owner 互換分岐の場合は 1 です。 |
| content.remark | string | 備考です。デフォルトは空文字列です。 |
| content.isBurnAfterReading | integer または boolean | 履歴表示用のマーカーです。通常の作成では 0 です。これを根拠に、後続のすべての読み取りで平文が返されないと判断することはできません。 |
| content.callCount | integer または null | 累計呼び出し回数です。新規作成のスナップショットはデータベースのデフォルト値が設定される前のため null になる場合があります。ローテーションしても過去の統計はリセットされません。 |
| content.lastCallAt | integer または null | 最終呼び出しの Unix 秒です。記録がない場合は通常 -1 です。新規作成のスナップショットは null になる場合があり、ローテーションしてもリセットされません。 |
| content.status | integer | 0 は正常です。削除後は 3 です。作成/ローテーションの成功時は 0 を返します。 |
| content.creator | string | 作成した識別情報の UUID です。 |
| content.updator | string | 最終更新した識別情報です。新規作成時は通常空文字列です。 |
| content.createAt | integer | 作成時の Unix 秒です。ローテーションしても最初の作成時刻が保持されます。 |
| content.updateAt | integer | 最終更新の Unix 秒です。作成時に更新がない場合は -1 です。 |
| content.deleteAt | integer | 削除の Unix 秒です。未削除の場合は -1 です。 |
| content.roleInfo | array<object> |
ロール要約の配列です。通常の分岐ではクエリで取得した有効なロール、owner 分岐では owner のみです。明示的に [] で作成した場合はここが [] になることがありますが、認証は引き続き wsAdmin にフォールバックするため、権限ゼロとみなすことはできません。ロールの完全な権限ツリーは返しません。 |
| content.roleInfo[].uuid | string | ロール UUID です。readOnly/wsAdmin/owner や、このワークスペースのカスタムロール UUID などです。 |
| content.roleInfo[].name | string | ロールの表示名です。表示名で uuid を代用することはできません。 |
| content.declaration | object | 現在のワークスペースの共通宣言です。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "wsak_example",
"workspaceUUID": "wksp_example",
"name": "automation_reader",
"ak": "<NEW-AK>",
"sk": "<NEW-SK>",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "仅读自动化",
"isBurnAfterReading": 0,
"callCount": null,
"lastCallAt": null,
"status": 0,
"creator": "wsak_caller",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"roleInfo": [
{
"uuid": "readOnly",
"name": "Read-only"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストのエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | 例に従って JSON オブジェクトを提供します。 |
| 400 | ft.AKNameRepeat | このワークスペースに同名のシステム以外かつ削除されていない Key(無効な Key を含む)が既に存在 | 同名の AK が既に存在します | 一覧で既に作成済みか確認し、どうしても新しい Key が必要な場合は一意の名前に変更します。 |
| 400 | ft.AKOnwerRepeat | リクエストに owner が含まれるが、ワークスペースにシステム以外かつ削除されていない owner Key が既に存在 | オーナーの AK が既に存在します | 既存の owner Key の管理されたローテーション手順を使用し、重複して作成しません。 |
| 400 | ft.InvalidRoleUUID | 通常分岐のいずれかのロールが無効/このワークスペースに未認可/無効化済みまたは削除済み | 無効なロール UUID: {} | 現在のワークスペースのロール一覧から有効な uuid を選び直します。 |
| 403 | ft.Forbidden | インターフェース権限が不足、または owner 以外の識別情報で owner Key を要求 | 操作する権限がありません | 条件を満たす管理 Key を使用し、可能な限り最小権限のロールを採用します。 |
| 401 | ft.WKSPNotExistOrReleased | リフレッシュ時に現在のワークスペースが存在しない、または非アクティブ状態 | ワークスペースが存在しない/または解放済み | 対象ワークスペースがまだアクティブであることを確認し、管理 Key をワークスペース間で再利用しないでください。 |
| 500 | ft.InternalServerError | データベースまたは認証情報キャッシュの無効化に失敗。ローテーション/削除がコミットされた後にエラーが返る可能性 | 内部エラー | まず別の有効な管理 Key で元の UUID とステータスを読み取ります。ローテーションのレスポンスが失われ、旧 Key が既に無効な場合は、別の有効な管理 Key で再度ローテーションし、新しい認証情報を安全に受け取ります。無効になった旧 Key で繰り返し再試行しないでください。 |