コンテンツにスキップ

検証



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&timestamp={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 バインドされたアカウントに有効なワークスペースメンバーシップがありません 対応するワークスペースメンバーが見つかりません。 このアカウントが現在もワークスペースのメンバーであるかどうかを確認してください。

フィードバック

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