2001: Authenticate

Authenticates an entity by checking whether, for example, the submitted username and password matches the data in the database, or a specific account on a social media is registered in the database.

Endpoint ID:

2001

Method:

POST

URL:

/entity/authenticate

Request body:

JSON data with type of authentication (native, facebook or onetime) along with data specific to type of authentication.

Required fields:
	authType “native”:	loginID password
	authType “facebook”:	appID (Facebook AppID) userID updatedAccessToken accessTokenExpires (UTC timestamp for when the access token expires)
	authType "onetime"	loginID password

Example 1 – Native authentication:

{
	"authType": "native",
	"loginID": "mailbox@mailserver.com",
	"password": "password"
}

Example 2 – Facebook authentication:

{
	"authType": "facebook"
	"appID": 987654321,
	"userID": 123456789,
	"updatedAccessToken": "...",
	"accessTokenExpires": "..."
}

JSON data with key(s) for successfully authenticated account. The result will always hold the Rubiq entity ID and if the app making the request is configured to use a specific external key, this key is also included in the response. If authentication fails, the result is empty.

Responses to native and facebook authType requests resemble 1001: Create account response data:

Native authenticate response example

{
    "id": 123456
    "name": "John Doe",
    "email": "mailbox@mailserver.com"
}

However authType: onetime responses may authenticate multiple entities, if they share the same loginID (e.g. email address), so onetype responses contain an array of entities, each with its own apiSessionKey property. There will not be an ApiSessionKey response header in a onetime authentication response. See Data Isolation for ApiSessionKey details.

Onetime password authentication response example

{
    "entities": [
        {
            "id": 123456
            "name": "John Doe",
            "email": "shared@mailserver.com",
            "apiSessionKey": "x7s8t2lb9yi4ozswqkqurw3lh"
        },
        {
            "id": 234567
            "name": "Jane Doe",
            "email": "shared@mailserver.com",
            "apiSessionKey": "qxai81njm9jd2scb55rdftcbw"
        }
    ]
}

Status codes:

200

Successfully authenticated

403

Invalid login

The following sub codes may be returned:

403.1	Unknown loginID
403.2	User has not been verified
403.3	User is not active
403.4	Incorrect password
403.7	Facebook appID not recognised
403.8	Facebook connection does not exist
403.9	The Facebook userID was found but the connection does not have a Rubiq entity ID
403.10	Too many incorrect attempts to log in - the password is temporarily locked
403.11	The password has expired