Skip to content

Login

Registered users can login to establish their identity with the application using the API below. The login operation requires two properties: one marked as user identity and the second is password. Backendless automatically assigns the "AuthenticatedUser" role to all successfully logged in users. The role can be used to differentiate access to various resources (persistent objects, messaging channels, files) between authenticated users and guests.

Method

POST

URL

https://api.backendless.com/application-id/REST-api-key/users/login

where:

Argument                Description
application-id the ID of your application. You can obtain the value in the Manage > App Settings section of the Backendless Console.
REST-api-key REST API key of your application. You can obtain the value in the Manage > App Settings section of the Backendless Console.

Request Headers

Content-Type:application/json

where:

Argument                Description
Content-Type must be set to application/json. This header is mandatory.

Request Body

{  
  "login" : value,  
  "password" : value,  
}

The "login" key must contain the value for the property marked as identity.

Response Body

{  
  "objectId" : value,  
  "user-token": value,   
  //all user properties (except for password) in the "prop-name":"prop-value" format  
  "prop-name1":value,  
  "prop-name2":value,  
  "prop-name3":value,  
  ...  
}

The "objectId" property is a unique identifier assigned by Backendless to the user account. The "user-token" value identifies the user session initiated by the Login operation. Both of these values ("objectId" and "user-token") are required for Updating User Properties.

Errors

When the server-side reports an error, it returns a JSON object in the following format:

{  
  "message":error-message,  
  "code":error-code  
}

The following errors may occur during the Login API call.

Error Code
Description
2002
Version is disabled or provided wrong application info (application id or secret key)
3000
Login has been disabled for the user account.
3001
Missing login settings, possibly invalid application id or version.
3002
User cannot login because Multiple Logins disabled and there is a logged in user for the account.
3003
Invalid login or password.
3006
Either login or password is an empty string value.
3034
User logins are disabled for the version of the application.
3036
Account locked out due to too many failed logins.
3038
One of the required parameters (application id, version, login or password) is null
3044
Multiple login limit for the same user account has been reached.
8000
Property value exceeds the length limit
curl   
  -H Content-Type:application/json   
  -X POST   
  -d '{"login":"jbond@007.com", "password":"watchingya"}'   
  -v   
  https://api.backendless.com/application-id/rest-api-key/users/login 

Maintaining User Session

The "user-token" value returned from the login must be used in the subsequent requests to Backendless in order to maintain user session. The value uniquely identifies both the user and the session on the server and is used to enforce security policy, apply user and roles permissions and track usage analytics. For all requests made after the login, the user-token value must be sent in the HTTP header:

"user-token":value

Validating User Login

The login operation provides a way to persist the user-token on the client side so it can be used when the application is restarted. This helps in streamlining the user experience since the user of the application does not need to login again. However, when the application restarts, it needs to check if the underlying user token, and hence the user session are still valid. This can be accomplished with the API below:

Method

GET

URL

https://api.backendless.com/<application-id>/<rest-api-key>/users/isvalidusertoken/<userToken>

where:

Argument                Description
<application-id> the ID of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console.
<rest-api-key> the key of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console.
<userToken> user token to validate. The value of the user token is returned by Backendless as a result of the login call.

Sample Request

curl   
-X GET   
-v https://api.backendless.com/application-id/rest-api-key/users/isvalidusertoken/<userToken>

Return value

The server returns a boolean value of true if token is valid, false otherwise.