Creates a new user in the application. A user is identified by their unique user ID, but they also each have a changeable nickname and a profile image.
When a user logs into Sendbird server through the Chat SDK, the user authentication can be conducted with just their user ID, or with either an access token or a session token. An access token can be issued when creating a user while a session token can be issued through the /users/{user_id}/token
endpoint. If a user has an issued token, the token must be provided to the server each time the user logs in through the Chat SDK.
Note: Issuing session tokens through the
/users/{user_id}
endpoint is now deprecated and it's replaced with/users/{user_id}/token
endpoint for greater efficiency. For those who are currently using the old endpoint, you can start issuing tokens using the new endpoint.
A session token generated by the new endpoint provides efficient authentication between the end user and Sendbird server. Unlike tokens generated through the previous method, new session tokens aren't stored in the Sendbird database. This improves the server's performance when a customer tries to issue a lot of tokens at once. After a session token is issued, the end user will be connected to Sendbird server for a set time period. Once the token expires, the user must request a new session token.
Note: For those who wish to replace the old endpoint with the new
/users/{user_id}/token
endpoint, there may be an issue with the session token length if the cache in your app has a limit imposed on the token string length. The new session tokens can have a string of from 119 to 168 characters.
Access token | Deprecated session token | New session token | |
---|---|---|---|
Endpoint | - |
| /users/{user_id}/token |
Used for | Stateful authentication |
| Stateless authentication |
Work as | Permanent credential to the system |
| Temporary credential to the system |
Valid or active until | Revoked |
| Timestamp set when issued (default: the next 7 days from now) |
Identification for | The user account |
| The user's current session |
Tokens per user | Up to 10 (valid) |
| No limit |
If exceeded the limit | The oldest token is revoked and the new one is added to the list. |
| No limit |
Auto-revocation | No |
| Yes (by default the system revokes the expired tokens) |
Note: It is recommended that you cache the session tokens of your users in their devices locally and use the cached tokens when logging in to Sendbird server. If you issue a new session token every time a user logs in to the server, multiple login attempts with different tokens of the user can occur simultaneously. Then, some sessions of the user can be locked out depending on the number of the attempts.
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
user_id | string | Specifies a user's unique ID. The length is limited to 80 characters. |
nickname | string | Specifies the user’s nickname. The length is limited to 80 characters. |
profile_url | string | Specifies the URL of the user’s profile image. If left empty, no profile image is set for the user. The length is limited to 2,048 characters. |
Optional | Type | Description |
---|---|---|
profile_file | file | Uploads the file of the user's profile image. Acceptable image file types are |
issue_access_token | boolean | Determines whether to create an access token for the user. If true, an opaque string token is issued and provided upon creation. The token is required each time the user logs in. If false, no access tokens will be issued or required when the user logs in. (Default: false) |
discovery_keys[] | array of strings | Specifies an array of unique keys of the user, which is provided to Sendbird server when searching for friends. The unique key acts as an identifier for users' friends to find each other. The server uses discovery keys to identify and match the user with other users. |
metadata | nested object | Specifies a |
| boolean | (Deprecated) Determines whether to create a session token for the user. If true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If false, a session token is not required when the user logs in. (Default: false) |
| long | (Deprecated) Specifies the time for the issued session token to expire in Unix milliseconds |
Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.
If successful, this action returns a user resource in the response body.
In the case of an error, an error object is returned. A detailed list of error codes is available here.