Enable/Disable¶
POST /api/v1/account/set-disable
Overview¶
Enable or disable specified accounts in batches.
Prerequisites and Usage Steps¶
Requires External credentials with w permission. Setting isDisable=true sets status=2 (disabled), while false sets status=0 (normal). When disabling, the system attempts to clear the account's login token and profile cache, and then asynchronously refreshes alert configurations in related workspaces. If token clearing fails, a log is recorded, but the API may still succeed; therefore, when forced logout must be guaranteed, ask the administrator to verify. Enabling does not restore the original token, and the member must sign in again. Unknown or deleted UUIDs are ignored, and setting the same status again can succeed again.
Request Headers¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| X-Df-SVersion | string | Signature version for the original path and request body; this value cannot be omitted if you continue to use the algorithm on this page. Example: v20240417How to obtain or enter: This page uses this fixed version, which matches the example signature algorithm. |
|
| X-Df-Access-Key | string | Y | Read endpoints accept r or w credentials; write endpoints require w credentials. Example: <external-access-key>How to obtain or enter: Assigned by the site administrator as an External API AK; do not use a workspace OpenAPI Key. |
| X-Df-Nonce | string | Y | Temporary serial number; when resending after a failure, also generate a new value and recalculate the signature. Example: 97d275ee9f774315a7885ba7347acbd9How to obtain or enter: Generate a new uuid.uuid4().hex for each request. |
| X-Df-Signature | string | Y | Concatenate the uppercase method, nonce, original full path, timestamp, and original UTF-8 request body separated by spaces, then compute HMAC-SHA256 and take the hex digest. Example: <hmac-sha256-hex>How to obtain or enter: Calculate using the matching SK as described in External API Signature Authentication; see the complete runnable template below. |
| X-Df-Timestamp | string | Y | Must fall within the signature validity window configured for the site; do not reuse the example time. Example: 1785427200How to obtain or enter: When sending, use str(int(time.time())) to generate the current Unix seconds string. |
Body Request Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountUUIDs[*] | string | A single target account UUID string, not a workspace UUID. Example: acnt_example001How to obtain or enter: Obtain each one from content.data[].uuid in Account List. |
|
| accountUUIDs | array | Y | Array of target account UUIDs; clients should first verify the scope and send a non-empty list of strings. An empty array does not affect all accounts in bulk; unknown or deleted UUIDs are ignored. Null allowed: False Example: ["acnt_example001"]How to obtain or enter: Obtain each one from content.data[].uuid in Account List; do not enter a wksp_ workspace UUID. |
| isDisable | boolean | Y | Required boolean, not a string; before disabling, confirm that the account still needs to be retained. Null allowed: False Allowed values: [True, False] Example: trueHow to obtain or enter: Choose true to disable or false to enable based on the desired status. |
Additional Parameter Notes¶
Use site-level External API credentials. For authentication, see External API Signature Authentication. The following example uses signature version v20240417; the signed path, query encoding, and original request body must exactly match what is actually sent. The returned account profile does not include a password field; mfaSecret is only a fixed mask, not a key that can be used for sign-in. This operation preserves workspace membership and role relationships; after re-enabling, the original associations remain. Success only indicates that the API flow is complete; verify status in the list.
Request Example¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# Replace with the target site address and the External API AK/SK assigned by the administrator.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/account/set-disable'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'isDisable': True}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
Response¶
HTTP 200 with Content-Type application/json and a unified response envelope. Business data is in content; External API does not automatically add declaration, and list pagination remains in content.pageInfo.
| Field | Type | Description |
|---|---|---|
| content | object | An empty object {} on success; it is not a per-account result, and unknown UUIDs do not produce individual errors. |
{
"code": 200,
"content": {},
"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 | Resolution |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | A request field is missing, or a field value violates the declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Invalid request JSON syntax | Request JSON format error | Correct the JSON based on content.reason, line, and column. |
| 400 | ft.JsonFormatError | The top level of the request body JSON is not an object | Partial JSON file format error | Use a JSON object; do not send an array, string, or null as the top level. |
| 400 | ft.AgentMemberCanNotDisable | Only when disabling with isDisable=true, the batch contains accounts with source=agent and status 0, 1, or 2 | Members from the agent source cannot be disabled | Remove the agent-source accounts from the batch and manage their status through the corresponding integration. |
| 500 | ft.InternalServerError | Database, cache, asynchronous task submission, or unhandled field exceptions | Internal error | Save the traceId and contact the administrator; for write requests, query the current account state again first, and only then decide whether to retry. Do not treat a 500 as having had no effect. |