Platform API

Get an administrator token

Use Get an administrator token to issue an administrator token for a configured application administrator. Your backend uses this token to call OpenIM management REST APIs. Configure the API address first as described in Prepare to use the API, and never send an administrator token to a client or embed it in frontend code.

HTTP request

POST {API_ADDRESS}/auth/get_admin_token

Request example

curl --request POST "${API_ADDRESS}/auth/get_admin_token" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --data-raw '{
  "secret": "openIM123",
  "userID": "imAdmin"
}'

Parameters

This endpoint accepts tracing information in request headers and business parameters in a JSON request body. It is on the router allowlist, so it does not require an administrator token.

Request headers

Header	Required	Type	Description
operationID	Yes	string	A unique tracing ID for this request. Generate it on the backend and include it in application logs.
Content-Type: application/json	Yes	string	Required when the request body is JSON.

Request body

{
  "secret": "openIM123",
  "userID": "imAdmin"
}

Parameter	Required	Type	Description
secret	Yes	string	The `secret` configured in the server-side `config/share.yml` file.
userID	Yes	string	An application administrator user ID configured on the server. The default is usually `imAdmin`.

Response

OpenIM usually returns 200 OK when the request reaches the service. Use errCode in the JSON response to determine business success; errCode === 0 means the operation succeeded.

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "token": "admin_or_user_token_sample",
    "expireTimeSeconds": 7776000
  }
}

Response fields

Field	Type	Description
errCode	int	Business error code. `0` means success.
errMsg	string	Short error message.
errDlt	string	Detailed error information for troubleshooting.
data	object	Endpoint-specific response data.
data.token	string	The issued application administrator token.
data.expireTimeSeconds	int	Token lifetime in seconds.

Error response

When a request fails, OpenIM returns the same error envelope. See Error codes for the full handling model.

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

Scenario	Possible cause	Recommended action
Authentication failed	`secret` is incorrect or `userID` is not a configured application administrator.	Check the server configuration and request a new administrator token.
Traceability is weak	`operationID` is missing or reused across many requests.	Generate a unique `operationID` for every request and log it with the response.
Validation failed	The request body has an invalid type, missing field, or unsupported enum value.	Compare the payload with the request table and retry after correcting the fields.

Permissions and limits

A successful request issues a new administrator token and records an administrator login.
secret must match the server configuration.
userID must identify an application administrator configured on the server.
This endpoint is on the router allowlist and does not require an administrator token.

Was this page helpful?