Skip to content

Obtain API Call Credential ​

This API must be called on the server side. Never call it directly from the frontend (APP client, web page, mini game, etc.) to avoid the risk of credential leakage.

API Description ​

API English name auth.getAccessToken

Description Obtain the API call credential (Access Token). This credential is the globally unique credential used by the APP server to call SUD OP SVR backend APIs, for identity authentication and API permission control. Third-party platform proxy calls are not supported.

Note: This API is called directly as a standard HTTPS request and does not support request encryption and signing. Pass app_id, secret and other parameters as a plaintext JSON body; the response is plaintext JSON. No encrypted payload, signature headers, or response decryption are needed.

Call Method ​

HTTPS Call ​

http
POST /v1/auth/token

Prepend the base URL for your application's service region to the API path. See Service Regions and API Addresses.

Request Parameters - Body ​

Please use application/json as the Content-Type.

FieldTypeDefaultRequiredDescription
grant_typestringYesFixed value client_credential
app_idstringYesUnique application identifier AppId
secretstringYesApplication secret (AppSecret)
force_refreshbooleanfalseNoForce refresh mode switch. false: normal mode, repeated calls within the validity period do not issue a new credential, and the current credential is returned with its remaining validity; true: force refresh mode, issues a new credential immediately, the old credential stays valid for 5 minutes and expires after that (so multi-node caches have time to update). Limited to 20 times per day, with an interval of ≥30 seconds between two calls

Return Value ​

The returned JSON data packet

FieldTypeDescription
errcodeint32Error code
errmsgstringError message
access_tokenstringThe obtained globally unique API call credential
expires_innumberCredential validity time, in seconds. In normal mode, the remaining validity of the current credential; in force refresh mode, the full validity of the newly issued credential, usually 7200 seconds (2 hours)

Call Example ​

Note: This API is called in plaintext. Both the request and response examples are the exact payloads sent and received; no encryption or signature is involved.

cURL Request ​

bash
# Mainland China example; use the corresponding base URL for other regions.
BASE_URL='https://cn-papi.sudbiz.cloud'

curl -X POST \
  "${BASE_URL}/v1/auth/token" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "grant_type": "client_credential",
  "app_id": "YOUR_APP_ID",
  "secret": "YOUR_APP_SECRET",
  "force_refresh": false
}'

Response Data Example ​

json
{
  "errcode": 0,
  "errmsg": "ok",
  "access_token": "ACCESS_TOKEN",
  "expires_in": 7200
}

Best Practices and Credential Management ​

To ensure the stability of API calls and the security of the system, developers are strongly advised to follow the guidelines below when obtaining and maintaining the access_token.

1. Credential Refresh and Management Architecture ​

  • access_token (dynamic credential): A short-lived credential that is read at high frequency. It must and can only be stored in a high-performance distributed cache (such as Redis), using the TTL mechanism to manage the expiration time.
  • Concurrency control: When credential expiration triggers renewal, a multi-node cluster should use a distributed lock to ensure that only one node initiates a refresh request to the SUD server at any given moment, avoiding a refresh storm that causes rate limiting.
  • Mode selection: When the cache holds no valid credential, obtain one in normal mode (force_refresh: false), which returns the still-valid credential together with its remaining validity. When entering the early-refresh window, you must use force refresh mode (force_refresh: true) to issue a new credential.
  • Smooth refresh: Use the expires_in returned in normal mode (remaining time) as the reference. Once the remaining time drops to 10 minutes or less, immediately refresh with force_refresh: true. After a force refresh the old credential remains valid for 5 minutes, which covers the window in which other nodes' caches have not been updated yet; do not wait until less than 5 minutes remain, otherwise a network jitter may leave you without a usable credential.
  • Refresh frequency: Constrained by the force_refresh limits (20 times per day, at least 30 seconds between calls), a 7200-second validity means about 12 scheduled refreshes per day, leaving headroom for retries; never let every business node issue its own force refresh.

Note: expires_in means different things in the two modes. In normal mode it is the remaining validity, which must not be used to overwrite the cache TTL with the full validity, otherwise a credential about to expire would be treated as a new one. In force refresh mode it is the full validity of the new credential, and the cache TTL should use this value directly.

Sequence logic reference:

If a refresh fails (network jitter, 5xx, rate limit), the old credential is still usable during the 5-minute grace period, so you can retry within that window; if it is still not refreshed after 5 minutes, subsequent API calls will fail authentication and should raise an alert.

2. General Security Precautions ​

  • Isolated storage of AppSecret: As a long-term sensitive static key, it must be stored in a secure storage medium on the APP server (such as a configuration center like Nacos/Apollo, or a Key Management Service KMS). Never hardcode it in code, configuration files, or frontend applications.
  • Whitelist restriction: It is recommended to configure a server IP whitelist in the SUD management console to block illegitimate Token acquisition requests at the source.