Users

User management is central to any application and central to Kinvey's backend-as-a-service.

The user management API has methods for handling typical user actions such as signup, login and logout. Using the API is as simple as calling each of those methods from the respective form and button in your app. An active user provides context for each interaction with your backend, ensuring that security is enforced and unauthorized access is disallowed. By default, a user's data is readable but not writable by other users.

A user object and its properties such as first name, last name and email are represented in the backend as an entity, and as such, most of the entity methods such as fetch and save apply.

Basic User Operations

The User API provides basic CRUD operations that an app can implement for managing users in its backend on Kinvey.

Sign up

Developers that choose to work directly with the User REST API should have POST /user/:appKey/ be the first call to Kinvey for a new application instance (fresh app install). The credentials should then be cached locally and used to authenticate any subsequent requests.

This request must be authenticated using Basic Auth with app credentials. The request body is optional, and may include any fields you might want to capture for the end user.

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]
Content-Type: application/json

[optional body]
HTTP/1.1 201 Created
Location: /user/:appKey/:_id
Content-Type: application/json

{
  "_id": "example-id",
  "username": "example-username",
  "password": "example-password-clear",
  "field1" "additional-field-passed-in",
  "fieldN" "additional-field-passed-in"
}

If the request does not contain a body, a username and password will be generated by the server and returned in clear text. If a specific username and password pair is needed by an app, they must be passed in fields called username and password respectively. The email address, used for password resets and email verification, must be stored in the email field.

Passwords are stored on the server hashed, using a random salt generated on the server. Subsequent GET requests for the user object do not return the hashed password or the salt.

If a request body is passed, it must be in a json format, and a Content-Type: application/json header must be used.

The returned Location header value can be used later to modify the user object.

The following example request creates a user with a username and password, along with two additional fields named city and interests:

POST /user/:appKey/ HTTP/1.1
Content-Type: application/json
Authorization: [Basic Auth with app credentials]
Content-Type: application/json

{
  "username": "ivan",
  "password": "123456",
  "city": "Boston",
  "interests": "Skiing"
}

Required headers

  • Authorization
  • Content-Type: application/json

Retrieve

A GET to /user/:appKey/:id fetches the user object.

GET /user/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

Authenticate using user credentials. The hashed password and the salt are excluded from the response.

The same robust querying available in the data store is valid for querying users including filtering, grouping and location queries. This querying respects the ACL setup for the collection and the users within.

Required headers

  • Authorization

Update

PUT /user/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
  "field1": "new-field",
  "field2": "field-to-be-updated"
}

This request updates the user entity at the location provided and is typically used when the user enters some new piece of information about themselves. Authenticate this request using user credentials.

Note that updating certain properties of a user entity will invalidate any existing user sessions, and generate a new auth token. These properties are: password, email, and _socialIdentity.

Required headers

  • Authorization
  • Content-Type: application/json

Delete

API Version 1

A DELETE request using API Version 1 will purge the user entity from the User collection. Subsequent requests for the same user will return a 404 Not Found error and the deleted user id/name will be available for re-use.

DELETE /user/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
X-Kinvey-API-Version: 1
HTTP/1.1 204 No Content

Additionally, with API Version 1 or above, apps have the ability to suspend a user. In API Version 1, this is done by specifying soft=true in the query string. Suspended users can no longer access the app and will receive a 401 error on all requests.

DELETE /user/:appKey/:id?soft=true HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
X-Kinvey-API-Version: 1
HTTP/1.1 204 No Content

User Deletes in API version 1

Suspended users continue to live in the User collection and can be re-enabled using the Master secret by sending a _restore request.

POST /user/:appKey/:id/_restore HTTP/1.1
Host: baas.kinvey.com
Authorization: [master secret]
X-Kinvey-API-Version: 1
HTTP/1.1 204 No Content

API Version 2

Starting with API Version 2, a plain delete that is not accompanied with a query string will automatically default to suspending the user instead of completely removing the entity, as described above.

User Deletes in API version 2

To permanently remove the user, include hard=true in the query string. This will completely remove the user from the User collection, and cannot be undone.

DELETE /user/:appKey/:id?hard=true HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
X-Kinvey-API-Version: 2
HTTP/1.1 204 No Content

Required headers

  • Authorization

User Sessions

User sessions allow you to secure access to the app using authorization tokens that can be controlled on a per session basis. Each session, beginning with a login and ending with a logout, allows you to model well defined periods of user engagement in the app.

Login

An app can use the login method - POST /user/:appKey/login - to log a user in. The method takes a username and password and, when validation is successful, returns the entire user entity.

With API version 1 or higher, the login method will also establish a session and return a Kinvey auth token, in the _kmd.authtoken property, that an app can use in subsequent requests for authentication.

The login request expects the user's credentials in the request body and must be authenticated with the app secret:

POST /user/:appKey/login HTTP/1.1
Content-Type: application/json
X-Kinvey-Api-Version: 1
Authorization: [Basic Auth with app credentials]

{
  "username": "ivan",
  "password": "123456"
}
HTTP/1.1 200 OK
X-Kinvey-Api-Version: 1
Content-Type: application/json

{
  "username": "ivan",
  "location": "Cambridge, MA, USA",
  "locale": "en-US",
  "_kmd":
  {
    "lmt":"2012-06-29T13:02:11.864Z",
    "authtoken":"368c9f15-01b4-4a49-9b8d-989f4b2d30ed.Vai/mloxDgUUiSwiRkA9kDvoBu5NvlZaEkGXrREY8G9="
  }
}

Note that updating certain properties of a user entity will invalidate any existing user sessions, and generate a new auth token. These properties are: password, email, and _socialIdentity.

Required headers

  • Authorization
  • Content-Type: application/json

An app can retrieve information on the logged in user by using GET /user/:appKey/_me. The request must be authenticated using either Basic Auth or Session Auth. This method will return the entire user entity for the authenticated user.

GET /user/:appKey/_me HTTP/1.1
Authorization: [user credentials]
HTTP/1.1 200 OK
Content-Type: application/json

{
  "username": "ivan",
  "location": "Cambridge, MA, USA",
  "locale": "en-US",
  "_kmd":
  {
    "lmt":"2012-06-29T13:02:11.864Z"
  }
}

Required headers

  • Authorization

Logout

When using Session Auth, the app can logout and terminate a user session by sending a POST request to /user/:appKey/_logout.

When authenticated with a valid Kinvey auth token, the logout request will destroy the token and return a HTTP 204 response. Any subsequent requests that use the same auth token will be rejected with the HTTP 401 Unauthorized response.

This method is only available when using API version 1 or higher.

POST /user/:appKey/_logout HTTP/1.1
X-Kinvey-Api-Version: 1
Authorization: Kinvey [auth token]
HTTP/1.1 204 OK
X-Kinvey-Api-Version: 1

Logout destroys the session’s associated auth token, such that subsequent attempts to re-use that token will yield a 401 Unauthorized (error) response.

When using a third-party Single Sign-On (SSO) identity provider (such as Ping Identity), the app’s logout action will destroy active session auth tokens within the Kinvey app, but SSO tokens may persist on third-party provider sites. Logout does not terminate tokens stored at third-party SSO websites using SAML or OAuth. Cookies that maintain these sessions may enable a logged out user to reopen a session and obtain a new session auth token. For instance, using Ping Identity with SAML-Redirect, the user will remain authenticated on Ping Identity website after logging out from the associated Kinvey application. This would enable a user to login to their Kinvey app after being logged out, i.e. if they remain logged in to Ping Identity.

User Management

User management features provide fully automated workflows that can be used to easily manage and secure user account information.

Email Verification

Building email verification into your app ensures that your users provide you with correct and valid email addresses that they own during sign-up.

Configuration

The Console exposes several options that control how email verification is handled for your app. These options can be reached by navigating to the Users section and opening the Settings panel. The following settings are available:

  • Enforce email verification: by default, new apps do not enforce email verification. This means that while your users can go through the email verification process, any user can log into your app -- regardless of whether or not their email address is verified. In order to restrict access only to those users who have successfully verified their email addresses, enable the Enforce email verification option. Note that when this option is enabled, you will not be able to create a new user that does not have an email address.

    • Always allow access to users created before date: this option will become available when you turn on Enforce email verification. If enabled, any users created before the date you specify will be able to log into your app regardless of whether or not their email is verified. This option is intended to support apps with an existing user base in which users were not previously required to verify their email. The option will allow these existing users to log in, but require email verification from all new users created after the specified date.
  • Automatically send verification email: if this option is enabled, a verification email will automatically be sent when users are created, or when they change their email address. If this option is not enabled, you will need to manually initiate the email verification process (as described below) for each user in order to verify their email address.

Workflow

The email verification process may be started either automatically (if the Automatically send verification email option described above is enabled) or manually. To manually initiate the email verification process for a user, send a POST request with an empty body to Kinvey, as follows:

POST /rpc/:appKey/:username/user-email-verification-initiate HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]
HTTP/1.1 204 No Content

This request will start the email verification process, and will cause an email to be sent to the user requesting they confirm their email address by clicking on a link included in the email body. The link is served by Kinvey and is valid for five days from the time of the email. The email address for a user must be stored in a property named email in the user object.

Email Verification Request

If the user started the verification process, the current verification status will be available in the _kmd.emailVerification property of the user entity.

{
   "_id":"507242b8a8fd60a5120020b4"
   "username":"2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
   "email":"johndoe@kinvey.com",
   "_kmd":
   {
      "lmt":"2012-10-08T03:04:24.034Z",
      "emailVerification":
      {
        "status":"confirmed",
        "lastStateChangeAt":"2012-10-10T19:56:03.282Z",
        "lastConfirmedAt":"2012-10-10T19:56:03.282Z",
        "emailAddress":"johndoe@kinvey.com"
      }
   },
   "_acl":
   {
     "creator":"507242b8a8fd60a5120020b4"
   }
}

The verification workflow exposes the following states in the status property:

  • sent: an email was sent in response to a verification initiate request
  • resent: multiple emails were sent in response to verification initiate requests
  • delivered: the email was successfully delivered to the user's mailbox (as reported by the remote server)
  • bounce: an email previously sent was bounced back by the remote server and couldn't be delivered
  • deferred: the mail system ran into transient problems delivering the email and deferred further attempts
  • dropped: the mail system dropped the email because of errors
  • confirmed: the user opened the email and clicked on the link enclosed in the email.

Each time the status changes, the time of change is recorded in the lastStateChangeAt property.

The workflow completes when the user opens and clicks on the link in the email, thus confirming their email address. A final email is then sent to the user letting them know that their email address was successfully confirmed.

Email Verification Completed

Note that the email address currently being verified is recorded in the emailAddress property of the _kmd.emailVerification object. Should the user change their email address (by changing the email property of their entity in the Users collection) while a verification is in progress, Kinvey will terminate the verification process for the previous email address, and start from the beginning with the new email address when a new initiate request is received.

The emailVerification object also tracks the last time the email address was confirmed in the lastConfirmedAt property. This is helpful if an app chooses to implement features to ensure ongoing validity of the email address on record.

Required headers

  • Authorization

Customization of verification emails

You have the option of customizing the contents and appearance of the emails that are sent to your app users. To customize these emails, navigate to the Branding section of the console. You'll see each of the user flows that involve emails or web pages from Kinvey, with the ability to modify each. You may modify the from and reply-to email fields, as well as the subjects and bodies of both the first email and the confirmation email.

Email Verification Customization

The From Address and Reply-To Address can be in the form: Display Name <account@server.com> or just account@server.com. Be aware that even if you change these fields, the email will still be sent from support@kinvey.com, and this might cause the message to be flagged by some mail clients.

The Subject and Email fields support mustache templates (tags within double curly-brackets). The email field supports HTML bodies, but a plain-text version will be generated and sent along in the message as well.

The available tags vary by email type. The available tags are:

Verification Email:

  • appname - the application name
  • fname - the user's first name, as specified by the first_name field in the user collection.
  • username - the user's username, as specified by the username field in the user collection. The first two lines of the default template are a switch that uses first name if available, and username if one is not.
  • url - the link the user needs to click to verify the email and show the verification page
  • expirationTimeDays - how many days the link is valid for (from generation time)
  • expirationDate - the exact date the link will expire

Congratulations Email:

  • appname - the application name
  • fname - the user's first name, as specified by the first_name field in the user collection.
  • username - the user's username, as specified by the username field in the user collection. The first two lines of the default template are a switch that uses first name if available, and username if one is not.
  • lastChangedAt - the time the user submitted a new password

Customization of successful verification page

You have the option of customizing the HTML "success" page that is displayed when a used has successfully verified their email by clicking the link sent to them.

Email Verification Success Page

The page supports mustache templates (tags within double curly-brackets). The available tags are:

  • appname - the application name
  • fname - the user's first name, as specified by the first_name field in the user collection
  • username - the user's username, as specified by the username field in the user collection
  • lastChangedAt - the time the user submitted a new password

Password Reset

Kinvey allows you to build a password reset feature in your app, through which your users can establish new passwords when needed.

To request a password reset, send a POST request with an empty body to /rpc/:appKey/:username/user-password-reset-initiate:

POST /rpc/:appKey/:username/user-password-reset-initiate HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]
HTTP/1.1 204 No Content

Note that it is also possible to initiate the password reset process using a user's email address instead of username. To do so, replace the username in the request above with the user's email, as follows:

POST /rpc/:appKey/:email/user-password-reset-initiate HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]
HTTP/1.1 204 No Content

This request will send an email containing a secure time-bound link to the email address on record for the user. The link is served by Kinvey and is valid for twenty minutes from the time of the email. A link can be used for only one reset. Submitting the form will update the password for the user. The user will also receive a confirmation email when they complete the password reset.

Requesting a password reset will invalidate any active session tokens for the user and require a new login on any device using the app.

Password Reset

The current reset status for a user is available in the _kmd.passwordReset property of the user entity.

{
   "_id":"507242b8a8fd60a5120020b4"
   "username":"2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
   "email":"johndoe@kinvey.com",
   "_kmd":
   {
      "lmt":"2012-10-08T03:04:24.034Z",
      "passwordReset":
      {
        "status":"InProgress",
        "lastStateChangeAt":"2012-10-10T19:56:03.282Z"
      }
   },
   "_acl":
   {
     "creator":"507242b8a8fd60a5120020b4"
   }
}

A status value of InProgress implies that a password reset email was sent at the time recorded in the lastStateChangeAt property. Once the user completes a reset, the status value changes to an empty string and the lastStateChangeAt property reflects the time the password reset was completed.

Required headers

  • Authorization

Password Reset Email Customization

You have the option of customizing how the email is presented to your app users by specifying the from and reply-to email fields as well as the subjects and bodies of the first email and the congratulations email.

Email Verification Customization

The From Address and Reply-To Address can be in the form: Display Name <account@server.com> or just account@server.com. Be aware that even if you change these fields will still be sent from support@kinvey.com, and this might cause the message to be flagged by some mail clients.

The Subject and Email fields support mustache templates (tags within double curly-brackets). The email field supports HTML bodies, but a plain-text version will be generated and sent along in the message as well.

The available tags vary by email type. The available tags are:

Reset Email:

  • appname - the application name
  • fname - the user's first name, as specified by the first_name field in the user collection.
  • username - the user's username, as specified by the username field in the user collection. The first two lines of the default template are a switch that uses first name if available, and username if one is not.
  • reseturl - the link the user needs to click to go to the reset password page
  • expirationTimeMins - how many minutes the link is valid for (from generation time)
  • expirationDate - the exact date the link will expire

Congratulations Email:

  • appname - the application name
  • fname - the user's first name, as specified by the first_name field in the user collection.
  • username - the user's username, as specified by the username field in the user collection. The first two lines of the default template are a switch that uses first name if available, and username if one is not.
  • lastChangedAt - the time the user submitted a new password

Using a Custom Password Reset Page

Rather than using the default password reset page hosted on Kinvey, you may optionally host a password reset page on your server. A link to this page will be included in the email sent to your app's users when they reset their password. Typically, you would select this option if you want your users to see a link pointing to your domain rather than to kinvey.com, and/or brand the page in any way you like to better fit your app's visual style.

Background and Process

In order to understand where your custom page fits in, it's helpful to understand the general password reset process:

  1. A user attempts to reset their password. Your app makes a request to the password reset endpoint, either directly or via a client library.

  2. Kinvey sends an email to the user, with a link to baas.kinvey.com/rpc/:kid/:usernameOrEmail/user-password-reset-process (including parameters such as time, nonce and sig).

  3. When the user clicks the link, your app's password reset page is dynamically generated by Kinvey's servers and displayed to the user.

  4. When the user submits the form on the password reset page, their browser requests baas.kinvey.com/rpc/:kid/:usernameOrEmail/user-password-reset-complete (again, with some additional parameters), which resets their password, and displays a confirmation page.

The custom password reset page that you will host will essentially replace the third step described above. A link to your page will appear in the email sent to the user, and your page will then be responsible for parsing the required parameters from the email's link and passing them, along with the new password, onto the Kinvey endpoint mentioned in step 3.

Template

The first step in creating your custom password reset page is downloading our template:

Download Template

The template contains a very simple password reset page that is modeled after our own. It contains a few lines of JavaScript code which parse the parameters from incoming URL, as well as a form allowing the user to input his new password. When the submit button is clicked, the form will send the required parameters to the Kinvey endpoint mentioned in step 3 above.

You are free to customize this form as you wish. Be aware that the Kinvey endpoint that completes the password reset process expects the data to be presented in a certain format, and you should be careful when modifying the JavaScript code or the form elements. After you have made your changes, always make sure that the newly modified page still works as expected by trying to reset a user's password through the Kinvey Console.

When you have finished customizing your password reset page, upload it to your server and make note of the URL. You will need to enter the page's URL in the next step.

Console Configuration

Once you have customized your page and uploaded it to your server, it is time to configure Kinvey so that it uses your page instead of the default one. To do so, open the Kinvey Console, navigate to the Users section, and open the Setting panel.

Select the Password Reset tab, and enter the URL for your custom page in the input field, and press the Save Changes button. This will complete the setup process, and your new page will now be used for all future password reset requests from your app.

It is highly recommended that you now test the password reset process in order to make sure that the changes you have made to the page are compatible.

Using Social Identities

An app can use social identities to setup user management in the backend. By offering options for users to login using their Facebook, Twitter, Google+, or LinkedIn accounts, an app removes a source of friction by not requiring that users create special usernames and passwords just for the app.

An app can register identities from multiple social networks under the same Kinvey user and switch between them as needed. This opens up the ability to offer multiple login options (e.g.: Login with Facebook and Login with Twitter) in the app.

Facebook

An app can have users login using their Facebook accounts. This allows an app to establish user identity using Facebook profiles.

The first step in using Facebook user information is to integrate the Facebook OAuth 2.0 workflow in the app.

Once a user installs the app on their device (shown in step (1) of diagram below), they will login with their Facebook username and password. On successful login, the app will receive an OAuth access token from Facebook. This is depicted in step (2) of the diagram below.

Using Facebook Identity - Setup

The app can then use this token to establish a user on Kinvey by doing a user create POST that includes the OAuth access token in the JSON of the request body:

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "facebook":
    {
      "access_token": "AAAD30ogoDZCYBAKS50rOwCxMR7tIX8F90YDyC3vp63j0IvyCU0MELE2QMLnsWXKo2LcRgwA51hFr1UUpqXkSHu4lCj4VZCIuGG7DHZAHuZArzjvzTZAwQ",
      "expires": "5105388"
    }
  }
}

Kinvey will validate the access token with Facebook and retrieve the corresponding user's identity from Facebook.

The response to a successful POST request will include the newly created Kinvey user and a Kinvey session token as well. This is depicted in step (3) in the diagram. Subsequent requests to Kinvey should use the session token for authentication.

Please note that as part of the data capture, Kinvey will automatically store the following Facebook user attributes in the app backend if they are returned by Facebook: id, name, gender, email, birthday, and location. No other Facebook data will be stored.

HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "503bc9806065332d6f000005",
  "username": "73abe64e-139e-4034-9f88-08e3d9e1e5f8",
  "password": "a94fa673-993e-4770-ac64-af82e6ab02b7",
  "_socialIdentity":
  {
     "facebook":
     {
        "id": "100004289534145",
        "name": "Kois Steel",
        "gender": "female",
        "email": "kois.steel@testFB.net",
        "birthday": "2012/08/20",
        "location": "Cambridge, USA"
     }
  },
  "_kmd":
  {
     "lmt": "2012-08-27T19:24:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "8d4c427d-51ee-4f0f-bd99-acd2192d43d2.Clii9/Pjq05g8C5rqQgQg9ty+qewsxlTjhgNjyt9Pn4="
  },
  "_acl":
  {
    "creator": "503bc9806065332d6f000005"
  }
}

Once a Kinvey user has been established, the app can use the login method to establish new Kinvey session tokens using any OAuth access tokens generated for the same Facebook user in the future. This is depicted in steps (4) to (6) of the diagram above.

POST /user/:appKey/login HTTP/1.1
Content-Type: application/json
X-Kinvey-Api-Version: 1
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "facebook":
    {
      "access_token": "AAAD30o1oDZCYBANq)cpD8ioyI2i8k5CMJn6ZAAhT2RuG27h3V4vYIY9CbegiuqbPkZHGyEaQibrEILmi9ePMBFZCZCtoKaYKKcInoQW1HUtZBWSK7mRrrn",
      "expires": "5105388"
    }
  }
}

Please note that we continue to offer the flexibility of using the two other forms of authentication Basic Auth and Session Auth for the Kinvey user. An app can do so by using the username/password credentials returned in the response to the user create request. This is useful if the app user chooses to not login using their Facebook account in the future.

When the app user does a logout out of Facebook, the app should immediately follow with a Kinvey logout using the Kinvey session token that was originally returned in response to the OAuth access token. This will ensure that access to the app backend terminates and that the user must do a fresh login before they can resume using the app. This is shown in Steps (1) to (3) of the diagram below.

Using Facebook Identity - Setup

An app can also purge Facebook identity for a user by doing an update using the Kinvey user id. Use the same syntax but set the reference to Facebook to NULL. This is shown in steps A to B of the second diagram. A purge also automatically destroys any outstanding Kinvey session tokens for the user. Note, user updates are full updates, so the request must contain the entire user object.

PUT /user/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
  "_socialIdentity":
  {
     "facebook": "null"
  }
}

Required headers

  • Authorization
  • Content-Type: application/json

Twitter

Similar to the Facebook feature described above, an app can have users login using their Twitter accounts. This allows the app to establish user identity using Twitter handles.

The first step in using Twitter user information is to integrate the Twitter OAuth 1.0a workflow in the app.

Once a user installs the app on their device, make them login using their Twitter handle and password. On successful login, the app will receive OAuth 1.0a credentials from Twitter. An app can use these credentials to establish a user on Kinvey by doing a user create POST that includes the credentials in the JSON of the request body:

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "twitter":
    {
      "access_token": "621982046-n1AXhkLS9aDir1E8k23q5scHw4FLUiNvcIuePhK8",
      "access_token_secret": "iObT0cXUwB8wzIBpgNOFJb12Vbqa8LuaW7Woac9o",
      "consumer_key": "2sCiJD119Cj86zID5jEXA",
      "consumer_secret": "rlUxyuue6n8LqO9P8wWW6S8fPT3Xt27qcMzXNMaPUB"
    }
  }
}

Kinvey will validate credentials with Twitter and retrieve the corresponding user's identity from Twitter.

The response to a successful POST request will include the newly created Kinvey user and a Kinvey session token for the new user. Subsequent requests to Kinvey should use the session token for authentication.

Please note that as part of the data capture, Kinvey will automatically store the following Twitter user attributes in the backend if they are returned by Twitter: description, id, lang, location, name, screen_name, and url. No other Twitter data will be stored.

HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "507242b8a8fd60a5120020b4",
  "username": "2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
  "password": "3fc29620-0cdd-419c-ac26-d6006ebab22c",
  "_socialIdentity":
  {
     "twitter":
     {
        "id": "12328904",
        "lang": "en",
        "name": "Kois Steel",
        "screen_name": "KoisSteel",
        "location": "Cambridge, USA",
        "url": "http://www.koissteel.com",
        "description": "Writer, Traveller, and Entrepreneur coach"
     }
  },
  "_kmd":
  {
     "lmt": "2012-10-17T21:14:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0="
  },
  "_acl":
  {
    "creator": "507242b8a8fd60a5120020b4"
  }
}

Just like the Facebook integration feature described above, an app can use the login method to establish new Kinvey session tokens for the user in the future. When the user does a logout out of Twitter, the app should immediately followup with a Kinvey logout using the session token that was established on login.

An app can purge Twitter identity for a user from the backend by by doing an update using the Kinvey user id with the reference to "twitter" set to NULL. A purge will also automatically destroy any outstanding Kinvey session tokens for the user.

Required headers

  • Authorization
  • Content-Type: application/json

Google+

Similar to the Facebook feature described above, an app can have users login using their Google+ accounts. This allows an app to establish user identity using Google+ identities.

The first step in using Google+ user information is to integrate the Google OAuth 2.0 workflow in the app. If the app is using Google services like Google Play, integrate the corresponding authentication workflow into the app.

Once a user installs the app on their device, the must login using their Google+ username and password. On successful login, the app will receive OAuth 2.0 credentials from Google. An app can use these credentials to establish a user on Kinvey by doing a user create POST that includes the credentials in the JSON of the request body:

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "google":
    {
      "access_token": "G2i9cA046-n1AXhkLS9aDir1E8k23q5scHw4FLUiNvcIuePhK8",
      "expires_in": "3600"
    }
  }
}

Kinvey will validate credentials with Google+ and retrieve the corresponding user's identity from Google.

The response to a successful POST request will include the newly created Kinvey user and a Kinvey session token as well. Subsequent requests to Kinvey should use the session token for authentication.

Please note that as part of the data capture, Kinvey will automatically store the following Google user attributes in the app backend if they are returned by Google: id, email, verified_email, name, given_name, family_name, link, gender, birthday, and locale. No other Google data will be stored.

HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "507242b8a8fd60a5120020b4",
  "username": "2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
  "password": "3fc29620-0cdd-419c-ac26-d6006ebab22c",
  "_socialIdentity":
  {
     "google":
     {
       "id": "904292911550952250171",
        "email": "Kois.Steel@gmail.com",
        "verified_email": true,
        "name": "Kois Steel",
        "given_name": "Kois",
        "family_name": "Steel",
        "link": "https://plus.google.com/904292988511957240352",
        "gender": "female",
        "birthday": "0000-01-01",
        "locale": "en"
     }
  },
  "_kmd":
  {
     "lmt": "2012-10-17T21:14:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0="
  },
  "_acl":
  {
    "creator": "507242b8a8fd60a5120020b4"
  }
}

Just like the Facebook integration feature described above, an app can use the login method to establish new Kinvey session tokens for this user in the future. When the user does a logout out of Google+, the app should immediately followup with a Kinvey logout using the session token that was established on login.

An app can purge Google+ identity for a user by by doing an update using the Kinvey user id with the reference to "google" set to NULL. A purge will also automatically destroy any outstanding Kinvey session tokens for the user.

Required headers

  • Authorization
  • Content-Type: application/json

LinkedIn

Similar to the Facebook feature described above, an app can have users login using their LinkedIn accounts. This allows an app to establish user identity using LinkedIn profiles.

The first step in using LinkedIn user information is to integrate the LinkedIn OAuth 1.0a workflow in the app.

Once a user installs the app on their device, make them login using their LinkedIn account and password. On successful login, the app will receive OAuth 1.0a credentials from LinkedIn. An app can use these credentials to establish a user on Kinvey by doing a user create POST that includes the credentials in the JSON of the request body:

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "linkedIn":
    {
      "access_token": "621982046-n1AXhkLS9aDir1E8k23q5scHw4FLUiNvcIuePhK8",
      "access_token_secret": "iObT0cXUwB8wzIBpgNOFJb12Vbqa8LuaW7Woac9o",
      "consumer_key": "2sCiJD119Cj86zID5jEXA",
      "consumer_secret": "rlUxyuue6n8LqO9P8wWW6S8fPT3Xt27qcMzXNMaPUB"
    }
  }
}

Kinvey will validate credentials with LinkedIn and retrieve the corresponding user's identity from LinkedIn.

The response to a successful POST request will include the newly created Kinvey user and a Kinvey session token as well. Subsequent requests to Kinvey should use the session token for authentication.

Please note that as part of the data capture, Kinvey will automatically store the following LinkedIn user attributes in the app backend if they are returned by LinkedIn: id, firstName, lastName, headline, and industry. No other LinkedIn data will be stored.

HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "507242b8a8fd60a5120020b4",
  "username": "2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
  "password": "3fc29620-0cdd-419c-ac26-d6006ebab22c",
  "_socialIdentity":
  {
     "linkedIn":
     {
        "id": "834923412328904",
        "firstName": "Kois",
        "lastName": "Steel",
        "headline": "Entrepreneur and Writer",
        "industry": "Entertainment"
     }
  },
  "_kmd":
  {
     "lmt": "2012-10-17T21:14:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0="
  },
  "_acl":
  {
    "creator": "507242b8a8fd60a5120020b4"
  }
}

Just like the Facebook integration feature described above, an app can use the login method to establish new Kinvey session tokens for this user in the future. When the user does a logout out of LinkedIn, the app should immediately followup with a Kinvey logout using the session token that was established on login.

An app can purge LinkedIn identity for a user by by doing an update using the Kinvey user id with the reference to "linkedIn" set to NULL. A purge will also automatically destroy any outstanding Kinvey session tokens for the user.

Required headers

  • Authorization
  • Content-Type: application/json

User Discovery

The full range of access control mechanisms is available for users. For example: an app may choose to mark the User collection Private, which will prevent one user from accessing another user's data. However, keeping user data hidden prevents app users from discovering other users, thus reducing the social value of the app. The _lookup method allows an app to respect user privacy but enable user discovery at the same time.

The lookup method provides a very limited way to query and retrieve some basic attributes on other users.

POST /user/:appKey/_lookup HTTP/1.1
Content-Type: application/json
Authorization: [user credentials]

{
  "username": "tom"
  "last_name": "Newman"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "_id": "58295028829"
  "username": "tom",
  "first_name": "Thomas"
  "last_name": "Newman"
  "email": "thomas.newman@emailprovider.com"
}

This method allows users to do exact queries for other users restricted to the following attributes:

  • _id
  • username
  • first_name
  • last_name
  • email
  • _socialIdentity.facebook.id
  • _socialIdentity.facebook.name
  • _socialIdentity.twitter.id
  • _socialIdentity.twitter.name
  • _socialIdentity.google.id
  • _socialIdentity.google.given_name
  • _socialIdentity.google.family_name
  • _socialIdentity.linkedIn.id
  • _socialIdentity.linkedIn.firstName
  • _socialIdentity.linkedIn.lastName

The method accepts attributes in the request body and presence of more than one attribute is treated as a logical conjunction of all attributes. Any other attributes in the User collection are hidden in the lookup method. A future release will allow the ability to configure this list through the Kinvey Console.

Note an app can always use fine grained permissions for allowing one user to grant access to another user when the collection is marked Private. When enabled, fine grained permissions open up access to the entire user object through other API methods.

Required headers

  • Authorization
  • Content-Type: application/json

User Groups

User groups allow an app to aggregate application users into groups and setup access control based on group membership. Access control automatically adjusts when a user joins or leaves a group.

Create

POST /group/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
  "_id": "G",
  "users": {
    "all": false,
    "list": [
       { "_type": "KinveyRef", "_collection": "user", "_id": "1" },
       { "_type": "KinveyRef", "_collection": "user", "_id": "3" },
       { "_type": "KinveyRef", "_collection": "user", "_id": "4" }
    ]
  },
  "groups": [
    { "_type": "KinveyRef", "_collection": "group", "_id": "G1" },
    { "_type": "KinveyRef", "_collection": "group", "_id": "G5" }
  ]
}
HTTP/1.1 201 Created
Location: /group/:appKey/:_id
Content-Type: application/json

{
  "_id": "G",
  "users": {
    "all": false,
    "list": [
       { _type: "KinveyRef", _collection: "user", _id: "1" },
       { _type: "KinveyRef", _collection: "user", _id: "3" },
       { _type: "KinveyRef", _collection: "user", _id: "4" }
    ]
  },
  "groups": [
    { _type: "KinveyRef", _collection: "group", _id: "G1" },
    { _type: "KinveyRef", _collection: "group", _id: "G5" }
  ],
  "_acl": {
    "creator": "5058c666474f050906000001"
  },
  "_kmd": {
    "lmt": "2012-10-20T22:01:25.159Z",
    "ect": "2012-10-20T22:01:25.159Z"
  }
}

Individual users can be included in a group by adding Kinvey references to the list array under the users property. Each reference links to a user within the app by specifying that user's _id. When an entity grants access to a group, every user listed in that group's users.list array is granted the same access.

If the all property of a group is set to true, all users of the app will be part of the group.

A group can also contain one or more nested groups. Every group listed in the groups array gets access to all entities that grant access to the containing group. Much like the users.list array mentioned above, the groups array contains Kinvey references, each referring to a specific group by that group's _id.

An app can use this functionality to model nested access via groups. For example: an app may grant access to company policy documents to the group "employees". The "employees" group contains the groups "managers" and "directors", since all managers and all directors are also employees of the company. By granting 'read' access to the group "employees", an app automatically grants read access to the groups "managers" and "directors".

Groups can be nested up to three levels deep. Please contact Kinvey support to discuss deeper nesting.

Authentication and authorization for group creation follows regular access control.

Required headers

  • Authorization
  • Content-Type: application/json

List

A GET to /group/:appKey will return all group objects.

GET /group/:appKey HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
HTTP/1.1 200 OK
Location: /group/:appKey
Content-Type: application/json

[{
  "_id": "A",
  "users": {
    "all": false,
    "list": [
       { _type: "KinveyRef", _collection: "user", _id: "1" }
    ]
  },
  "_acl": {
    "creator": "5058c666474f050906000001"
  },
  "_kmd": {
    "lmt": "2012-10-20T22:01:25.159Z",
    "ect": "2012-10-20T22:01:25.159Z"
  }
}, {
  "_id": "B",
  "users": {
    "all": true
  },
  "_acl": {
    "creator": "5058c666474f050906000001"
  },
  "_kmd": {
    "lmt": "2012-11-20T22:01:25.159Z",
    "ect": "2012-11-20T22:01:25.159Z"
  }
}]

Authenticate using user context or master secret. Authorization for reads follows regular access control.

Required headers

  • Authorization

Retrieve

A GET to /group/:appKey/:id fetches the group object.

GET /group/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

Authenticate using user context or master secret. Authorization for reads follows regular access control.

Required headers

  • Authorization

Update

PUT /group/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

<JSON-Document-representing-UserGroup>

Use an Update request to change members of the group and/or change the groups contained in the group. Authentication and authorization for updates follows regular access control.

Required headers

  • Authorization
  • Content-Type: application/json

Delete

A group can be removed by issuing a delete request.

It's important that the app admin clean ACL metadata in the backend before deleting a group in order to prevent a reincarnation of the same group from getting access based on old metadata.

DELETE /group/:appKey/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
HTTP/1.1 204 No Content

Authentication and authorization for deletes follows regular access control.

Required headers

  • Authorization

Username Existence Check

In order to quickly check whether a specific username already exists within your app, you can use the check-username-exists RPC endpoint. To do so, POST a request to /rpc/:appKey/check-username-exists using your app credentials. The body of the request should contain a JSON object having a username field, which contains the username which you would like to check.

POST /rpc/:appKey/check-username-exists HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]
Content-Type: application/json

{
  "username": "the-username-to-check"
}

Kinvey will respond with a JSON object having a usernameExists field, which is set to true if the username exists within your app, or false if the username does not yet exist.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "usernameExists": "false"
}

Required headers

  • Authorization
  • Content-Type: application/json

Locked-down Users

The app administrator has the ability to lock-down a user. When a user is in locked-down state, any requests that are authenticated with this user's credentials or that attempt to log-in the user will fail. Additionally, all auth tokens for the user will be destroyed. Since this is an administrative operation, only the master secret can be used to lock-down a user (or unlock that user if already locked-down). In order to lock a user down, use the lockdown-user RPC endpoint as follows:

POST /rpc/:appKey/lockdown-user HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]
Content-Type: application/json

{
  "userId": "the-id-of-the-user-to-lock-down",
  "setLockdownStateTo": true/false
}

If the request was successful, Kinvey will respond with a JSON object containing the current status of the lock-down flag, and a status code of 200.

HTTP/1.1 200 OK
Content-Type: application/json

{
  currentLockdownStatus: true/false
}
Got a question?