User Registration
When establishing a connection with the IM service, the client must pass the user's authentication token (Token) for the IM service. The Token serves as the unique identifier for the user in the IM service. Whether using the IM service or the RTC service, this Token is required. Obtaining a Token signifies that a user has completed registration in the IM service.
Before proceeding, we recommend reading the User Overview to understand the related interfaces, services, and configurations for user management.
Obtaining a Token
The client SDK does not provide an API for obtaining a Token. You need to integrate the IM service's Token API on your App Server to implement the business logic for obtaining a Token.
Once the Token is successfully obtained, your App Server distributes it to the client. The client uses this Token when connecting to the IM service. The Token remains valid for use within its expiration period. For detailed information on Token expiration, refer to Invalidating Tokens.
The same user ID can obtain a Token multiple times. If the Token is within its validity period, it can be used to connect to the IM service. For a reference solution and UML flowchart on how the app obtains and uses the Token for connection and authentication, see the Using the Token section below.
Once you refresh the App Secret in the Console, all Tokens obtained under the App Key will become invalid. Please use the new App Secret to generate API signatures and obtain a new Token.
Request Method
Exchange the user ID (userId) defined at the app layer for an authentication Token used in the IM service. The same interface is used to re-obtain a Token for the same user ID.
POST: https://Data Center Domain/user/getToken.json
Signature Rule: All server API requests require rule validation. For details, refer to API Request Signing.
Rate Limit: 200 requests per second
Body Parameters
The HTTP request body data format is application/x-www-form-urlencoded, and the following HTTP form parameters are supported:
The name (name) and avatar (portraitUri) passed when obtaining the Token are only used for remote push notifications on mobile devices. If you need to change the name or avatar information, it is recommended to use the Modify User Information method. If new data is passed when re-obtaining the Token, it will overwrite the old name and avatar data.
| Parameter | Type | Required | Description |
|---|---|---|---|
| userId | String | Yes | The user ID defined by the app, used to exchange for a Token. Supports a combination of uppercase and lowercase English letters and numbers, with a maximum length of 64 bytes. |
| name | String | Yes | The user name used by the push service. Symbols, English characters, and Chinese characters are not distinguished, with a maximum length of 64 characters. Note: The name field is only used for push services, as the default user name displayed in push notifications on mobile clients. Since the IM service does not provide user profile hosting, the client SDK cannot actively retrieve this user name data. |
| portraitUri | String | No | The URI of the user's avatar, with a maximum length of 1024 bytes. Note: Since the IM service does not provide user profile hosting, the client SDK cannot actively retrieve this user avatar data. |
- If sending a one-to-one chat message, only the userId is needed to locate the recipient. For security reasons, it is strongly recommended that developers avoid using consecutive user IDs during registration to prevent malicious exploitation.
- In some older versions of the Server SDK, the
portraitUrifield is required. If you do not wish to fill in this field, please upgrade the Server SDK to the latest version or pass a fixed character, such as "_".
Request Example
POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded
userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg
Response
The HTTP response body contains a JSON object with the following structure:
| Return Value | Type | Description |
|---|---|---|
| code | Int | Return code, 200 indicates success. |
| token | String | The user authentication Token, with a length of up to 256 bytes, which can be saved within the app. The Token contains the IM service's dynamic navigation address, which developers do not need to process. |
| userId | String | The user ID provided in the input parameters. |
Response Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"code":200, "userId":"jlk456j5", "token":"sfd9823ihufi"}
Using the Token
The IM service does not manage any app user information. User registration only requires exchanging a user ID for a Token.
Your app client needs to handle Token invalidation when establishing an IM connection and request a new Token from the App Server when the Token is invalid.
Below is a reference solution for Token-based authentication and connection.
Obtaining a Token During the First Connection
After the app obtains the Token, it can choose to store the current user's Token locally. The process is as follows:
Using an Existing Token for Non-First Connections
During subsequent logins, there is no need to request a Token from the IM service again. The App Server directly provides the previously saved Token.
- Implement the code logic to re-obtain the Token from the server to handle Token invalidation.
- Tokens have an expiration period, which is permanent by default but can be modified in the Console.
- Refreshing the App Secret or invalidating the Token will render the existing Token invalid.
If your app is designed for login-free access, you can also store the Token locally within the app (ensure local data storage security) and log in directly.