検証¶

POST /api/v1/workspace/accesskey/verify

概要¶

現在の API Key または AccessKey SK token を検証します。

Body リクエストパラメータ¶

パラメータ名	型	必須	説明
version	any		新しい SK token プロトコルバージョン。`20260617` を指定すると timestamp のみが必要で、nonce/signature は不要です。例: 20260617 空を許可: True
timestamp	integer	Y	ミリ秒単位のタイムスタンプ。サーバーは現在時刻から 10 分以内のリクエストのみ受け付けます。例: 1711111111000 空を許可: False
nonce	string		旧署名プロトコルのフィールド。クライアントが生成するランダム文字列。長さ 16～128 文字、英数字、`.`、`_`、`:`、`-` のみ許可。例: 2b7c3a9e4f6545b7aef09a23f9e0c001 空を許可: True
signature	string		旧署名プロトコルのフィールド。sk を使用して固定署名文字列から計算された 64 文字の HMAC-SHA256 16 進小文字文字列。例: 3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a 空を許可: True

パラメータ補足説明¶

このインターフェースは、リクエストヘッダー DF-API-KEY 内の sk を検証するために使用します。検証が成功すると、現在の API Key の所属アカウント、ロール、権限情報が返されます。レスポンスには ak/sk フィールドは含まれません。

version=20260617 の新しいプロトコル¶

リクエストヘッダー DF-API-KEY には、現在の OpenAPI 呼び出しで使用する sk を必ず指定してください。
リクエストボディには version=20260617 と timestamp を指定します。
timestamp はミリ秒単位のタイムスタンプです。サーバーは現在時刻との差が 10 分以内のリクエストのみ受け付けます。
新しいプロトコルでは nonce と signature は不要です。
version は数値 20260617 の指定を推奨します。サーバーは文字列 "20260617" も受け付けます。

旧署名アルゴリズム¶

リクエストヘッダー DF-API-KEY には、現在の OpenAPI 呼び出しで使用する sk を必ず指定してください。
version=20260617 を指定しない場合、リクエストボディには従来通り timestamp、nonce、signature を指定します。
timestamp はミリ秒単位のタイムスタンプです。サーバーは現在時刻との差が 10 分以内のリクエストのみ受け付けます。
nonce はクライアントが生成するランダム文字列です。長さ 16～128 文字、英数字、.、_、:、- のみ許可されます。同一 API Key で記録された同じ nonce は 10 分以内に 1 回しか使用できません。
署名アルゴリズムは HMAC-SHA256 固定で、64 文字の 16 進小文字文字列を出力します。
署名文字列は次のように固定されます：ak=<ak>&method=POST&nonce=<nonce>&path=/api/v1/workspace/accesskey/verify&timestamp=<timestamp>。
上記 <ak> は、呼び出し側がローカルに保持し、現在の sk とペアリングされていることを検証したい ak です。リクエストヘッダーやリクエストボディには含めません。
signature = HMAC-SHA256-HEX(secret=<sk>, message=<署名文字列>)

リクエスト例¶

curl 'https://openapi.guance.com/api/v1/workspace/accesskey/verify' \
  -H 'DF-API-KEY: <sk>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  --data-raw '{"version": 20260617, "timestamp": 1711111111000}' \
  --compressed

旧署名を使用した呼び出し例：

curl '<Endpoint>/api/v1/workspace/accesskey/verify' \
  -H 'DF-API-KEY: <sk>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  --data-raw '{"timestamp": 1711111111000, "nonce": "2b7c3a9e4f6545b7aef09a23f9e0c001", "signature": "3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a"}' \
  --compressed

レスポンス¶

{
    "code": 200,
    "content": {
        "uuid": "wsak_xxx",
        "name": "func-ak",
        "workspaceUUID": "wksp_xxx",
        "createdWay": "manual",
        "accountUUID": "",
        "accountInfo": null,
        "effectiveAccountUUID": "wsak_xxx",
        "roles": [
            {
                "uuid": "readOnly",
                "name": "読み取り専用メンバー"
            }
        ],
        "permissions": [
            "data.query"
        ],
        "rolePermissions": {
            "readOnly": [
                "data.query"
            ]
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}

検証¶

概要¶