Platform API

Get a user token

Use Get a user token from your backend to issue a token for a specific user and login platform. The client uses this token to log in to the OpenIM SDK. Configure the API address as described in Prepare to use the API, and keep the administrator token on the backend only.

HTTP request

POST {API_ADDRESS}/auth/get_user_token

Request example

curl --request POST "${API_ADDRESS}/auth/get_user_token" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "platformID": 2,
  "userID": "user_001"
}'

Parameters

This endpoint accepts tracing and authentication information in request headers and business parameters in a JSON request body.

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.
token	Yes	string	An application administrator token. Keep it on the backend only.
Content-Type: application/json	Yes	string	Required when the request body is JSON.

Request body

{
  "platformID": 2,
  "userID": "user_001"
}

Parameter	Required	Type	Description
platformID	Yes	int	The user's login platform. See `PlatformID`. The administrator platform ID is not allowed.
userID	Yes	string	The registered regular user for whom the token is issued.

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 user 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	`token` is missing, expired, or not an administrator token.	Issue a new administrator token and keep it on the backend.
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 user token and stores its state on the server.
The request must use an application administrator token.
platformID cannot be the administrator platform ID.
userID cannot identify an application administrator or a notification account.
The target user must already be registered with OpenIM.

Was this page helpful?