Verification¶

POST /api/v1/workspace/accesskey/verify

Overview¶

Verify the current API Key or AccessKey SK token.

Body Request Parameters¶

Parameter Name	Type	Required	Description
version	any		New SK token protocol version. When set to 20260617, only timestamp is required, nonce/signature are no longer required. Example: 20260617 Allow empty: True
timestamp	integer	Y	Millisecond timestamp. The server only accepts requests within 10 minutes. Example: 1711111111000 Allow empty: False
nonce	string		Legacy signature protocol field. A random string generated by the client, length 16-128, only allowing letters, numbers, ., _, :, -. Example: 2b7c3a9e4f6545b7aef09a23f9e0c001 Allow empty: True
signature	string		Legacy signature protocol field. A 64-bit HMAC-SHA256 hex lowercase string calculated using the sk against a fixed signature string. Example: 3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a Allow empty: True

Parameter Supplementary Explanation¶

This interface is used to verify the sk in the current request header DF-API-KEY. Upon successful verification, it returns the account, role, and permission information associated with the current API Key. The response does not include the ak/sk fields.

version=20260617 New Protocol¶

The request header DF-API-KEY must contain the sk used for the current OpenAPI call.
The request body should include version=20260617 and timestamp.
timestamp is a millisecond timestamp. The server only accepts requests where the timestamp differs from the current time by no more than 10 minutes.
The new protocol no longer requires nonce and signature.
It is recommended to pass version as the number 20260617. The server is compatible with the string "20260617".

Legacy Signature Algorithm¶

The request header DF-API-KEY must contain the sk used for the current OpenAPI call.
When version=20260617 is not passed, the request body should continue to pass timestamp, nonce, and signature according to the legacy protocol.
timestamp is a millisecond timestamp. The server only accepts requests where the timestamp differs from the current time by no more than 10 minutes.
nonce is a random string generated by the client, length 16-128, only allowing letters, numbers, ., _, :, -. The same nonce recorded for the same API Key can only be used once within 10 minutes.
The signature algorithm is fixed as HMAC-SHA256, outputting a 64-bit hex lowercase string.
The signature string is fixed as: ak=<ak>&method=POST&nonce=<nonce>&path=/api/v1/workspace/accesskey/verify&timestamp=<timestamp>.
In the above, <ak> is the ak held locally by the caller, which needs to be verified to pair with the current sk. It is not placed in the request header or body.
signature = HMAC-SHA256-HEX(secret=<sk>, message=<signature string>).

Request Example¶

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

Legacy signature call:

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

Response¶

{
    "code": 200,
    "content": {
        "uuid": "wsak_xxx",
        "name": "func-ak",
        "workspaceUUID": "wksp_xxx",
        "createdWay": "manual",
        "accountUUID": "",
        "accountInfo": null,
        "effectiveAccountUUID": "wsak_xxx",
        "roles": [
            {
                "uuid": "readOnly",
                "name": "Read-only Member"
            }
        ],
        "permissions": [
            "data.query"
        ],
        "rolePermissions": {
            "readOnly": [
                "data.query"
            ]
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}