コンテンツにスキップ

ローテーション



POST /api/v1/workspace/accesskey/{ak_uuid}/rotate

概要

現在のワークスペースで指定した手動 API キーをローテーションし、リソース UUID とロール設定を保持します。

呼び出し前の確認と使用手順

現在のワークスペースで workspace.openAPIKeyManage 権限を持つ OpenAPI キーを使用します。ルート宣言には freeEdition のバージョン制限が記載されていますが、現在の OpenAPI 認証チェーンではこのバージョンチェックは実行されません。バージョン自体を必ず 403 になるものとして説明することはできません。可用性はデプロイと実際の権限に基づいて確認してください。リソーススコープは常にリクエストヘッダーのキーが属するワークスペースとなり、ボディでワークスペースを切り替えることはできません。owner キーの場合は、現在のアイデンティティに owner が含まれることも要求されます。インターフェース管理権限自体がこのチェックを代替するものではありません。

まず、このワークスペース内で有効かつシステム以外で、accountUUID が空の手動キーを特定し、新しい認証情報を受け取る準備をして、それを使用する自動化/SDK と調整します。リクエストにボディは不要です。新しい ak/sk を生成して保存し、uuid、名前、備考、ロール、作成時刻および呼び出し統計を保持します。その後、新しいキーのキャッシュを更新し、古い ak/sk を無効として書き込みます。成功後、古い認証情報は引き続き使用できません。すでに開始されたリクエストは取り消される保証はありません。

現在のキーは自身をローテーションできます。現在のリクエストは認証済みのため完了でき、その後で返された新しい認証情報に切り替えます。新しい認証情報の保存が成功してから呼び出し元を更新し、最後の管理キーを失わないようにします。作成およびローテーションのレスポンスには ak/sk の平文が含まれるため、直ちに管理された認証情報ストアに書き込みます。OpenAPI の認証ヘッダーにはキー値(たとえば返却された sk)を使用し、wsak_ リソース UUID は使用しないでください。以降の一覧/詳細は、呼び出し元のアイデンティティ、対象が手動かアカウント紐付けか、および現在のキーかどうかの影響を受け、マスクされる可能性があります。後続の読み取りに依存して失われた認証情報を復元しようとしないでください。また、現在のサービス実装を、すべてのアイデンティティで今後一切平文を返さないと説明することもできません。

ローテーションは冪等ではなく、実行するたびに新しい値のペアに交換されます。データベースのコミット後にキャッシュの無効化が失敗すると、500 が返る可能性があります。このとき、古い認証情報が短時間まだ使用できるかどうかをエラーコードだけで判断することはできません。別の有効な管理キーで読み戻すか、再度ローテーションして対処する必要があり、リトライを同じ結果の再実行として扱わないでください。

パスパラメータ

パラメータ名 型 必須 説明
ak_uuid string Y 現在のワークスペースのキーリソース UUID。ak/sk の平文や他のワークスペースの UUID は指定できません。
例: wsak_example
取得または入力方法: API キー一覧 の content[].uuid または作成レスポンスの content.uuid から取得します。必要に応じて API キー詳細 で確認してください。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API キー管理から、この操作権限を持つ OpenAPI キーを取得します。

パラメータ補足

ローテーションは新しい ak/sk を返すため、直ちに安全に保存して使用側を置き換えます。古い認証情報は、ローテーションおよびキャッシュ無効化の完了後は引き続き使用できません。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/workspace/accesskey/wsak_example/rotate' \
  -H 'DF-API-KEY: <DF-API-KEY>'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。

フィールド 型 説明
content.id integer または null データベース番号。新規作成レスポンスではコミット前のスナップショットのため null になる場合があります。以降の操作では uuid を使用します。
content.uuid string wsak_ で始まる API キーリソース UUID。詳細/削除/ローテーションのパスに使用します。DF-API-KEY の値ではありません。
content.workspaceUUID string 現在の呼び出しキーが属するワークスペース UUID。
content.name string キー名。
content.ak string 新しく生成された ak の平文。リソース uuid ではなく、呼び出しサービスの認証情報規約に従って使用します。
content.sk string 新しく生成された sk の平文。OpenAPI の DF-API-KEY として使用できます。直ちに安全に保存し、ログに書き込まないでください。
content.accountUUID string 紐付けアカウント UUID。このエントリポイントで作成した場合は空文字列となり、アカウント紐付け認証情報は作成されません。
content.createdWay string 作成元。このエントリポイントでは manual です。
content.businessType string 互換用の業務分類。通常の手動キーでは空文字列です。
content.isSystem integer または boolean システム組み込みフラグ。通常の手動キーでは 0/false です。
content.isOwnerRole integer または boolean owner キーかどうか。通常のロールで作成した場合は 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": 101,
    "uuid": "wsak_example",
    "workspaceUUID": "wksp_example",
    "name": "automation_reader",
    "ak": "<ROTATED-AK>",
    "sk": "<ROTATED-SK>",
    "accountUUID": "",
    "createdWay": "manual",
    "businessType": "",
    "isSystem": 0,
    "isOwnerRole": 0,
    "remark": "仅读自动化",
    "isBurnAfterReading": 0,
    "callCount": 20,
    "lastCallAt": 1785427250,
    "status": 0,
    "creator": "wsak_caller",
    "updator": "wsak_caller",
    "createAt": 1785427200,
    "updateAt": 1785427300,
    "deleteAt": -1,
    "roleInfo": [
      {
        "uuid": "readOnly",
        "name": "Read-only"
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラーレスポンス

認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対処方法
404 ft.AKNotExistOrDelete 対象が存在しない、ワークスペースをまたぐ、削除済み/無効、システムキー、またはアカウント紐付けキーがローテーションのクエリ条件に一致しない 指定された AK は存在しないか、削除されています 現在のワークスペースの一覧から有効な手動キーを選択します。アカウント紐付け認証情報は所属アカウントのフローを使用します。
403 ft.Forbidden 管理権限が不足している、または owner 以外が owner キーをローテーションしようとした 操作権限がありません 対象を管理する権限を持つキーを使用します。
500 ft.InternalServerError データベースまたは認証情報キャッシュの無効化に失敗。ローテーション/削除がコミットされた後にエラーが返る可能性がある 内部エラー まず別の有効な管理キーで元の UUID と状態を読み取ります。ローテーションのレスポンスが失われ、古いキーがすでに無効な場合は、別の有効な管理キーで再度ローテーションし、新しい認証情報を安全に受け取ります。無効になった古いキーで繰り返しリトライしないでください。

フィードバック

このページは役に立ちましたか?