Skip to content

Rotate



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

Overview

Rotate a specified manual API Key in the current workspace. The resource UUID and role configuration are retained.

Prerequisites and Usage Steps

Use an OpenAPI Key in the current workspace that has the workspace.openAPIKeyManage permission. The route declaration marks a freeEdition version restriction, but the current OpenAPI authentication chain does not enforce this version check, so the version itself must not be described as necessarily returning 403. Verify availability based on the deployment and actual permissions. The resource scope always uses the workspace to which the request header Key belongs; you cannot switch workspaces via the body. An owner Key also requires the current identity to include owner; API management permissions themselves do not replace this check.

First locate an active, non-system manual Key in this workspace with an empty accountUUID, prepare to receive the new credentials, and coordinate the automation/SDK that uses it. The request does not require a body; generate a new ak/sk and save it, retaining the uuid, name, remarks, roles, creation time, and call statistics, then refresh the Key cache and mark the old ak/sk as invalid. After success, the old credentials can no longer be used; requests that have already started are not guaranteed to be revoked.

The current Key can rotate itself. The current request is already authenticated and can complete; afterward, switch to the new credentials returned. Update the caller only after the new credentials are saved successfully, to avoid losing the last management Key. Create and rotate responses contain ak/sk in plaintext; write them immediately to controlled credential storage. The OpenAPI authentication header uses the Key value (for example, the returned sk), not the wsak_ resource UUID. Subsequent list/detail responses may be masked depending on the calling identity, whether the target is manual/account-bound, and whether it is the current Key. Do not rely on subsequent reads to recover lost credentials, and do not describe the current service implementation as never returning plaintext again for all identities.

Rotation is not idempotent; each call replaces the pair with new values. If cache invalidation fails after the database commit, a 500 may be returned. In this case, whether the old credentials can still be used briefly cannot be inferred solely from the error code; use another valid management Key to read back or rotate again. Do not treat a retry as replaying the same result.

Route Parameters

Parameter Type Required Description
ak_uuid string Y Key resource UUID in the current workspace. Do not enter ak/sk plaintext or a UUID from another workspace.
Example: wsak_example
How to obtain or enter: Obtain it from content[].uuid in the API Key List or from content.uuid in the create response; if necessary, verify it using API Key Details.

Request Headers

Parameter Type Required Description
DF-API-KEY string Y OpenAPI authentication credential for the workspace.
Example: <DF-API-KEY>
How to obtain or enter: Obtain an OpenAPI Key with this operation permission from API Key management in the target workspace.

Additional Parameter Notes

Rotation returns a new ak/sk. Save it securely immediately and replace the consumer; the old credentials can no longer be used after rotation and cache invalidation are complete.

Request Example

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

Response

HTTP 200, application/json. The example below shows the main fields that can be read directly.

Field Type Description
content.id integer or null Database ID. For create responses, this is a pre-commit snapshot and may be null; subsequent operations use uuid.
content.uuid string API Key resource UUID starting with wsak_, used in details/delete/rotate paths; this is not the DF-API-KEY value.
content.workspaceUUID string UUID of the workspace to which the current calling Key belongs.
content.name string Key name.
content.ak string Newly generated ak in plaintext; this is not the resource uuid. Use it according to the credential conventions of the calling service.
content.sk string Newly generated sk in plaintext, which can be used as the OpenAPI DF-API-KEY; save it securely immediately and do not write it to logs.
content.accountUUID string Bound account UUID; when created through this entry point, it is "" and no account-bound credentials are created.
content.createdWay string Creation source; for this entry point, it is manual.
content.businessType string Compatibility business category. For a regular manual Key, this is an empty string.
content.isSystem integer or boolean System built-in flag. For a regular manual Key, this is 0/false.
content.isOwnerRole integer or boolean Whether this is an owner Key; for regular role creation it is 0, and for the owner compatibility branch it is 1.
content.remark string Remarks. Defaults to an empty string.
content.isBurnAfterReading integer or boolean Historical display flag. For regular creation it is 0; this must not be used to infer that all subsequent reads will never return plaintext.
content.callCount integer or null Cumulative call count; the create snapshot may be null before database defaults are populated. Rotation does not reset historical statistics.
content.lastCallAt integer or null Most recent call time in Unix seconds; usually -1 if not recorded. The create snapshot may be null. Rotation does not reset it.
content.status integer 0: normal; 3 after deletion. Successful creation/rotation returns 0.
content.creator string UUID of the creating identity.
content.updator string Most recent modifying identity; usually an empty string on creation.
content.createAt integer Creation time in Unix seconds; rotation retains the original creation time.
content.updateAt integer Most recent update time in Unix seconds; -1 if not updated after creation.
content.deleteAt integer Deletion time in Unix seconds; -1 if not deleted.
content.roleInfo array<object> Array of role summaries; the regular branch contains the queried effective roles, while the owner branch contains only owner. When explicitly created with [], this can be [] here, but authentication still falls back to wsAdmin; this must not be taken to mean zero permissions. The complete role permission tree is not returned.
content.roleInfo[].uuid string Role UUID, such as readOnly/wsAdmin/owner or a custom role UUID in the current workspace.
content.roleInfo[].name string Role display name; do not use the display name in place of uuid.
content.declaration object Public declaration for the current workspace.
{
  "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"
}

Error Responses

For authentication, rate limiting, and common request errors, see Common Error Definitions.

HTTP Status errorCode Trigger Condition Message or Response Description Handling
404 ft.AKNotExistOrDelete The target does not exist, is in another workspace, has been deleted/disabled, or is a system Key or account-bound Key that does not meet the rotation query conditions The specified AK does not exist, or has been deleted Select an active manual Key from the current workspace list; for account-bound credentials, use the process for the account they belong to.
403 ft.Forbidden Insufficient management permissions, or a non-owner attempts to rotate an owner Key You do not have permission to perform this operation Use a Key that has permission to manage the target.
500 ft.InternalServerError Database or credential cache invalidation failure; rotation/deletion may have been committed before the error is returned Internal error First use another valid management Key to read the original UUID and status. If the rotation response is lost and the old Key has become invalid, use another valid management Key to rotate again and securely receive the new credentials; do not repeatedly retry with the invalid old Key.

Feedback

Is this page helpful?