/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Create a user

    Copy link

    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. Using this 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.


    Access token vs. Session token

    Copy link

    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.

    Deprecation Information

    Copy link

    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.

    Access tokenDeprecated
    session token
    New session token

    delete endpoint

    /users/{user_id}/access_token

    N/A

    /users/{user_id}/token

    create endpoint

    No specific endpoint. Set issue_access_token to true when creating a user.

    No specifc endpoint. Set issue_access_token to true when creating a user.

    /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)


    HTTP request

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

    Request body

    Copy link

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

    Properties
    RequiredTypeDescription

    user_id

    string

    Specifies a user's unique ID. Maximum length is 80 characters.

    * Do not use PII (Personally Identifiable Information) such as user email address, legal name, or phone number as it could jeopardize data security and privacy.

    nickname

    string

    Specifies the user's nickname. Maximum length is 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. Maximum length is 2,048 characters. If the profile_url property is specified, the profile_file property is not required.

    * Your application's domain filter filters out the request if the value of this property matches the filter's domain set.

    profile_file

    binary

    Specifies the file of the user's profile image. An acceptable image is limited to a JPG, JPEG, or PNG file of up to 5 MB. When passing a file, you should send a multipart request. If the profile_file property is specified, the profile_url property is not required.

    OptionalTypeDescription

    issue_access_token

    boolean

    Determines whether to create an access token for the user. If set to true, an access token will be generated and returned in the access_token field. This token must be passed to the Sendbird server when a user tries to connect. This should be set to true in all real-world apps. (Default: false)

    metadata

    nested object

    Specifies a JSON object to store up to five key-value items for additional user information such as their preference settings. The key must not have a comma (,), and the value must be a string.

    * If you're making a multipart request to upload the user's profile image, you need to call a separate user metadata API to add metadata to the user.

    * Do not use PII (Personally Identifiable Information) such as user email address, legal name, or phone number as it could jeopardize data security and privacy.

    issue_session_token

    boolean

    (Deprecated) Determines whether to create a session token for the user. If set to true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If set to false, a session token isn't 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 a value of this property is not specified and the issue_session_token property above is set to true, the value of this property is set to the sum of the current timestamp and 604800000 by default, meaning seven days starting from the current timestamp.

    * This property is deprecated and we encourage you to use the expires_at property instead for all Sendbird applications when issuing session tokens with the new /users/{user_id}/token endpoint.

    {
        "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": {
            "font_preference": "times new roman",
            "font_color": "black"
        }
    }
    

    Responses

    Copy link

    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": {
            "font_preference": "times new roman",
            "font_color": "black"
        }
    }
    

    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
    }