Create a user

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.

Access token vs. Session token

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}~~	/users/{user_id}/token
Used for	Stateful authentication	~~Stateless~~ ~~authentication~~	Stateless authentication
Work as	Permanent credential to the system	~~Temporary 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)~~*	Timestamp set when issued (default: the next 7 days from now)
Identification for	The user account	~~The user's current session~~	The user's current session
Tokens per user	Up to 10 (valid)	~~Up to 100* (valid)~~*	No limit
If exceeded the limit	The oldest token is revoked and the new one is added to the list.	~~The oldest and active 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)~~	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.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/users

Request body

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. * Do not use any PII (Personally Identifiable Information), such as user email address, legal name, or phone number.
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. * The domain filter can deny the request if the value of this property matches the filter's domain set.

Optional	Type	Description
profile_file	file	Uploads the file of the user's profile image. Acceptable image file types are `JPG` (.jpg), `JPEG` (.jpeg), or `PNG` (.png) of up to 25 MB.
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 `JSON` object to store key-value items that have additional user information such as phone number, email, or a long user description. The key must not have a comma (,) and its length is limited to 128 characters. The value must be a string and its length is limited to 190 characters. This property can have up to five items.
~~issue_session_token~~	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) * This property is deprecated and we encourage you to issue session tokens with the new `/users/{user_id}/token` endpoint for all Sendbird applications.
~~session_token_expires_at~~	long	(Deprecated) Specifies the time for the issued session token to expire in Unix milliseconds format. The length should be 13. If not specified and the `issue_session_token` property above is true, the value of this property is set to the sum of the current timestamp and 604800000 by default, meaning 7 days starting from the current timestamp. * This property is deprecated and we encourage you to use the `expires_at` property for all Sendbird applications when issuing session tokens with the new `/users/{user_id}/token` endpoint.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.

Request body example

{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "issue_access_token": true,
    "session_token_expires_at": 1542945056625,
    "discovery_keys": ["123-456-7890", "654-321-0987"],
    "metadata": {
        "location": "Seoul",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

Response

If successful, this action returns a user resource in the response body.

Status: 200 OK

{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "access_token": "07a0ccf6d3e801223e65b06b6066352e0512b43c",
    "is_online": false,
    "last_seen_at": -1,
    "discovery_keys": ["123-456-7890", "654-321-0987"],
    "preferred_languages": [],
    "has_ever_logged_in": false,
    "metadata": {
        "location": "Seoul",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

In the case of an error, an error object is returned. A detailed list of error codes is available here.