Create a user

You should create a user in your Sendbird application to initiate conversations in channels. A user is identified by its unique user ID, and additionally have a changeable nickname, profile image, and so on. Users are at the core of all conversations. Sendbird applications are made up of users who chat in either Open Channels or Group Channels. With the User API, it is possible to have fine grained control over your users and what those users can do. To learn more about users, see User Overview.

When a user logs into the Sendbird system through the SDKs, you should authenticate the user with either an access token or a session token. It is possible to log in just using a user ID, but a more secure authentication process using tokens is strongly recommended for most production environments.

Between the two types of tokens, session tokens are considered more secure because they expire after a given time while access tokens are valid until explicitly revoked.

Session tokens are issued by calling the /users/{user_id}/token endpoint after a user is created.

Access tokens are issued when a user is updated or created with the issue_access_token property set to true.

If either type of token is issued for a user, it must be provided to the Sendbird server each time the user logs in by using the SDK's connect methods. If you delete a user's token, the user won't be able to log in until a new token is issued.

Issuing session tokens through the /users/{user_id} endpoint is now deprecated and it's replaced with the /users/{user_id}/token endpoint for higher efficiency. For those who are currently using the old endpoint, you can start issuing tokens using the new endpoint. 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.

A session token generated by the new endpoint provides efficient authentication between the end user and the Sendbird server. Unlike the previous method of issuing session tokens, the new session tokens aren't stored in the Sendbird database. This method 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 is connected to the Sendbird server for a set time period. Once the token expires, the user must request a new session token.

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 the 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.

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

The following table lists the properties of an HTTP request that this action supports.

{
    "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,
    "metadata": {
        "location": "Seoul",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

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

{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "access_token": "07a0ccf6d3e801223e65b06b6066352e0512b43c",
    "is_online": false,
    "is_active": true,
    "is_created": true,
    "phone_number": "",
    "require_auth_for_profile_image": false,
    "session_tokens": [],
    "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 like below is returned. See the error codes section for more details.

{
  "message":"\\"user_id\\" violates unique constraint.",
  "code":400202,
  "error":true
}