How to login using the Cosync REST API

Login to user account. This function is passed a handle and a password parameter. The password parameter must be in MD5 format.

If the user has two-factor authentication enabled, the login function simply returns a StatusCode of 200 along with a login-token. If the application’s two-factor verification is phone, the Cosync service sends a six-digit code to the user’s phone number. If the phone number is not verified and two-factor authentication is enabled, the login will fail. For two-factor authentication, the client application must call loginComplete to complete the login. If the application’s two-factor verification is google, the user can retrieve the six digit code from the Google authentication application for login. This Google authentication code is used in the call to loginComplete.

If there is no two-factor verification for the user account, the login function will send back a JWT token that contains

• aud - audience (the Realm App Id)
• sub - subject (the user login handle - email)
• exp - an expiration date for the JWT token
• iat - the issue date for the JWT token
• metadata fields - metadata for the user

The metadata fields are defined by the application metadata array of metaDataField objects. Each metaDataField object defines a path and a field name. The root of the path shows up as a claim on the JWT token, fields are child properties.

The JWT token is signed with the application private key that is held by the Cosync JWT service. The JWT token is used to login into MongoDB Realm by the client device.

The login function will also send back a signed access token for the logged in user. This access token contains:

• handle - user email handle
• appId - CosyncJWT application id
• scope - user
• iat - time at which claim was issued

If two-factor authentication is turned on for the user, the login function will return a signed login-token instead of a JWT token and an access token. The signed login token contains:

• handle- user email handle
• appId - CosyncJWT application id
• iat - time at which claim was issued

This login token is used as parameter to the LoginComplete function described below.

• handle

URL

    /api/appuser/login

Method

    POST

Headers

	app-token: "<App Token>"

Data Parameter

    {
        handle: "<user handle>",
        password: "<user password>"
    }

Response:

Success:

StatusCode:

    200 (OK)

Contents:

    {
        jwt: "<JWT for logged in user>",
        access-token: "<access token for user>": 
    }
    or
    {
        login-token: "<signed login token>",
    }

Error:

StatusCode:

    400 (BAD REQUEST)
    500 (INTERNAL SERVER ERROR)

Content:

    {
        code: "<internal error code>",
        message: "<readable error description>"
    }

The internal codes are integers:

• 400 - invalid app token
• 401 - app no longer exists
• 402 - app is suspended
• 403 - missing parameter
• 404 - user account is suspended
• 500 - internal server error
• 600 - invalid login credentials