Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API

    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 tokenDeprecated
    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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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.

    {
        "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.

    {
        "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.