Obtain API Call Credential

This interface should be called on the server side. It must never be called directly from the front end (APP client, web page, minigame, etc.) to avoid the risk of credential leakage.

Interface Description

Interface Name auth.getAccessToken

Description Obtain the API call credential (Access Token). This credential is the globally unique credential used by the minigame server to call SUD OP SVR back-end interfaces, and is used for identity verification and interface permission control.

Note: This interface is called directly as a standard HTTPS request and does not support service communication secondary encryption and signatures. Pass game_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. Because secret is a high-risk credential, this interface must only be called from the server side.

Call Method

HTTPS Call

POST /v1/auth/token

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

Request Parameters - Body

Use application/json for Content-Type.

Field	Type	Default	Required	Description
grant_type	string		Yes	Fixed as client_credential
game_id	string		Yes	Unique game identifier
secret	string		Yes	Game secret (GameSecret)
force_refresh	boolean	false	No	Force refresh mode switch. false: normal mode, repeated calls within the access_token validity period do not update the access_token; true: force refresh mode, invalidates the previously obtained access_token and returns a new access_token

Response

The returned JSON data package

Field	Type	Description
errcode	int32	Error code
errmsg	string	Error message
access_token	string	The obtained API call credential
expires_in	int32	Credential validity period, in seconds. Usually 7200 seconds (2 hours)

Example

cURL Request

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

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

Response Example

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

Best Practices and Credential Management

To ensure the stability of interface calls and the security of the system, developers are strongly advised to follow the specifications 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 its expiration time.
• Concurrency control: When credential expiration triggers a 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.
• Smooth refresh: To avoid token invalidation caused by network jitter in extreme cases, it is recommended to proactively initiate a refresh 5-10 minutes before expires_in expires.

Sequence logic reference:

2. General Security Precautions

• Isolated storage of GameSecret: This is a long-term sensitive static key. It must be stored in a secure storage medium on the minigame server (such as a configuration center like Nacos/Apollo, or a Key Management Service (KMS)). It must never be hard-coded in code, configuration files, or front-end 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.