Create and authenticate an entity, receive and use the dpKey

A basic sign-up process involves creating an entity (user) and receiving their dpKey (id). This is simply done by making an authenticated request to endpoint 1001: Create account:

{
   "firstName": "Alan",
   "lastName": "Turing",
   "userName": "a_turing",
   "password": "3n1gm4"
}
{
   "dpKey": 12345,
   "firstName": "Alan",
   "lastName": "Turing",
   "userName": "a_turing"
}

The request and response fields depend on your app contract: you may have more or fewer fields, with different names etc. The only static field is the dpKey in the response body.

 

The entity has now been created, and the dpKey from the response can be used to update or remove the entity, change the password, assign tracks, add social connections etc. In most situations, the API accepts the dpKey as a URL parameter, so Alan's details could be retrieved with a GET request to this URL:

https://api.dialogportal.com/v1/user/dp-key/12345/data

 

If you choose to store the dpKey indefinitely in your app, then you will not need to authenticate the entity. However, if you only want to use short-term storage, or provide log-in functionality for existing entities, then you can use endpoint 2001: Authenticate to validate the user, and retrieve the dpKey:

{
   "authType": "native",
   "loginID": "a_turing",
   "password": "3n1gm4"
}
{
   "dpKey": 12345,
   "firstName": "Alan",
   "lastName": "Turing",
   "userName": "a_turing"
}

The response here is the same as the response from endpoints 1001: Create account and 1002: Get account data, and the fields depend on the contract. However, the 2001: Authenticate request is static, so the loginID and password shown here are always called "loginID" and "password", even though the contract loginID field may be called "userName" (as in this example) or "email" etc.