検証¶
POST /api/v1/workspace/accesskey/verify
概要¶
現在の呼び出しで使用している Secret Key を検証し、アイデンティティと権限のコンテキストを取得します。
呼び出し前と使用手順¶
現在の OpenAPI Secret Key を DF_API_KEY に設定します。新しいプロトコルでは version=20260617 と現在の Unix ミリ秒タイムスタンプを使用します。呼び出し元がローカルに保存している AK/SK のペアを検証する必要がある場合は、旧プロトコルを使用し、ローカルの AK と SK で署名を計算します。有効な DF-API-KEY を渡した場合にのみ検証に到達できます。API が成功するとアイデンティティ、ロール、権限が返され、認証情報フィールドはこの API では返されません。クライアントは引き続き、バインドされたアカウント情報を機密情報として扱う必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | 現在の OpenAPI 呼び出しを開始する完全な SK。 例: <SK>取得または入力方法: ワークスペースの API Key 管理から、この Secret Key の完全な値を取得します。 |
リクエストボディのパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| version | any | 20260617 を指定した場合、SK token プロトコルを使用します。 null を許可: True 例: 20260617取得または入力方法: 新プロトコルを使用する場合は 20260617(数値または文字列)を入力します。旧プロトコルを使用する場合は省略します。 |
|
| timestamp | integer | Y | サーバーの現在時刻との差が 10 分を超えてはなりません。 null を許可: False 例: 1785427200000取得または入力方法: 呼び出し時にシステムクロックで現在の Unix ミリ秒数を生成します。例の固定値は実際の送信には使用できません。 |
| nonce | string | 旧プロトコルでは必須です。16~128 文字で、英字、数字、および . _ : - を使用できます。同じ Key の値は 10 分以内に重複してはなりません。 null を許可: True 例: 2b7c3a9e4f6545b7aef09a23f9e0c001取得または入力方法: 旧プロトコルでは uuid.uuid4().hex を使用して毎回異なる nonce を生成できます。 |
|
| signature | string | 旧プロトコルでは必須です。64 桁の小文字十六進数です。例の値はプレースホルダーです。 null を許可: True 例: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef取得または入力方法: ローカルの AK を署名対象文字列の計算に使用し、SK で HMAC-SHA256 を実行して、例に従って生成します。 |
パラメータの補足説明¶
例に含まれるリソース識別子はプレースホルダー値です。対象ワークスペースの実際の値に置き換えてください。
リクエスト例¶
ts=$(python3 -c 'import time; print(int(time.time()*1000))')
curl --fail-with-body "https://openapi.guance.com/api/v1/workspace/accesskey/verify" \
-H "DF-API-KEY: $DF_API_KEY" \
-H "Content-Type: application/json" \
--data-raw "$(printf '{"version":20260617,"timestamp":%s}' "$ts")"
旧プロトコルの署名計算例
import hmac
import json
import os
import time
import uuid
from urllib.request import Request, urlopen
ak = os.environ["DF_ACCESS_KEY_ID"]
sk = os.environ["DF_API_KEY"]
nonce = uuid.uuid4().hex
timestamp = int(time.time() * 1000)
source = f"ak={ak}&method=POST&nonce={nonce}&path=/api/v1/workspace/accesskey/verify×tamp={timestamp}"
signature = hmac.digest(sk.encode(), source.encode(), "sha256").hex()
payload = {"timestamp": timestamp, "nonce": nonce, "signature": signature}
endpoint = os.environ["OPENAPI_ENDPOINT"].rstrip("/")
request = Request(endpoint + "/api/v1/workspace/accesskey/verify",
data=json.dumps(payload).encode("utf-8"),
headers={"DF-API-KEY": sk, "Content-Type": "application/json"},
method="POST")
with urlopen(request, timeout=15) as reply:
verified = json.load(reply)["content"]
レスポンス¶
HTTP 200、application/json。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uuid | string | API Key レコードの UUID。一般的なプレフィックスは wsak_ です。API Key 管理 API のパスで使用します。 |
| content.name | string | API Key の名前。 |
| content.workspaceUUID | string | 所属ワークスペース。 |
| content.createdWay | string | API Key の作成元。 |
| content.remark | string | API Key の備考。 |
| content.isOwnerRole | integer または boolean | この API Key にワークスペースオーナーのロールがあるかどうか。 |
| content.callCount | integer | 記録された呼び出し回数。 |
| content.lastCallAt | integer | 最後に記録された呼び出し時刻(Unix 秒)。記録がない場合は -1 になることがあります。 |
| content.createAt | integer | レコードの作成時刻(Unix 秒)。 |
| content.accountUUID | string | 明示的にバインドされたアカウント UUID。未バインドの場合は空文字列です。 |
| content.effectiveAccountUUID | string | 認証に使用するアイデンティティ識別子。未バインドの場合はこの API Key レコードの UUID です。 |
| content.accountInfo | object または null | バインドされたアカウント情報。未バインドの場合は null です。 |
| content.roles | array<object> |
有効なロールのセット。順序は固定されません。 |
| content.roles[].uuid | string | ロール UUID。 |
| content.roles[].name | string | ロール名。 |
| content.permissions | array<string> |
有効な権限識別子のセット。順序は固定されません。 |
| content.rolePermissions | object | 各ロールが持つ権限識別子。ロール UUID をキー、権限文字列の配列を値とします。 |
| content.declaration | object または null | ワークスペース宣言。 |
{
"code": 200,
"content": {
"uuid": "wsak_example",
"name": "应用数据读取",
"workspaceUUID": "wksp_example",
"createdWay": "manual",
"remark": "",
"isOwnerRole": 0,
"callCount": 14,
"lastCallAt": 1785427200,
"createAt": 1785423600,
"accountUUID": "",
"effectiveAccountUUID": "wsak_example",
"accountInfo": null,
"roles": [
{
"uuid": "role_example",
"name": "应用数据只读"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example": [
"routine.defaultAccess"
]
},
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーの詳細は共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答の説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | フィールドの型、必須、または制約がパラメータ表と一致しません | リクエストフィールドの検証に失敗しました。メッセージにフィールドまたはルールが示されます。 | フィールド、型、制約を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラーです。 | content 内の reason、line、column を読み取って修正してください。 |
| 400 | ft.JsonFormatError | Body の JSON のトップレベルがオブジェクトではありません | JSON 形式エラーです。 | JSON オブジェクトを送信してください。 |
| 401 | ft.APIAkKeyFailed | リクエストに認証ヘッダーがありません | リクエストヘッダーに AK Key がありません。 | DF-API-KEY に完全な SK を渡してください。 |
| 401 | ft.InvalidAPIKey | 認証情報またはバージョンに必要なフィールドの不一致、タイムスタンプの無効、旧署名の不正、または nonce の重複 | 無効な API Key です。 | 認証情報を確認し、時刻を同期して、プロトコルに従って署名と nonce を再生成してください。 |
| 403 | ft.AgentMemberDisabled | API Key にバインドされたアカウントが無効化されています | バインドされたアカウントは使用できません。 | バインドされたアカウントが使用可能な状態かどうかを確認してください。 |
| 404 | ft.AgentMemberNotFound | API Key にバインドされたアカウントが存在しないか、削除されています | バインドされたアカウントが見つかりません。 | バインド関係とアカウントの状態を確認してください。 |
| 404 | ft.WorkspaceAgentMemberNotFound | バインドされたアカウントに有効なワークスペースメンバーシップがありません | 対応するワークスペースメンバーが見つかりません。 | このアカウントが現在もワークスペースのメンバーであるかどうかを確認してください。 |