Authentication is the first layer of security in this connected vehicle mobile SDK. This layer of security will log in the user using email & password, this will request and store a token required for most of this SDK APIs.

Check Authentication Status #

First, we should check if the user is already logged in.

In case the response result returns the user login, it means that the user is logged.

Otherwise, you should use the login API.

1
2
3
4
5
6
7
pims.get("pims.authentication.account",
  mapOf( /* parameters */
  Pair("actionType", "basic"),
  Pair("type", "username")
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
7
pims.get(api: "pims.authentication.account", 
  parameters: [
  "actionType": "basic",
  "type": "username"
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
7
8
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "login": "name@provider.com"
  }
}

Login #

In case the user is not already authenticated, you should use the login API. Calling this API will prompt an External User-Agent (for native apps it can be the system browser) where the user will be able to log in.

If the status of the response is succeeded, you can use the API requiring Authentication ✅.

1
2
3
4
5
6
7
pims.set("pims.authentication.user",
  mapOf( /* parameters */
  Pair("action", "login")
  Pair("context", context)
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
pims.set(api: "pims.authentication.user", 
  parameters: [
  "action": "login"
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}

Logout #

If you need to log out the user, you should use the logout method.

In case the response is succeeded, the user is successfully logged out.

1
2
3
4
5
6
7
pims.set("pims.authentication.user",
  mapOf( /* parameters */
  Pair("action", "logout")
  Pair("context", context)
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
pims.set(api: "pims.authentication.user", 
  parameters: [
  "action": "logout"
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}

Create an Account #

You should implement a “Create an account” feature if the user doesn’t have one. Calling this API will prompt an External User-Agent (for native apps it can be the system browser) where the user will be able to create the account.

1
2
3
4
5
6
7
pims.set("pims.authentication.user",
  mapOf( /* parameters */
  Pair("action", "createAccount")
  Pair("context", context)
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
pims.set(api: "pims.authentication.user", 
  parameters: [
  "action": "createAccount"
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}

Update Login #

To add a “update login” feature, implement the following api. Calling this API will prompt an External User-Agent (for native apps it can be the system browser) where the user will be able to update the login.

1
2
3
4
5
6
7
pims.set("pims.authentication.user",
  mapOf( /* parameters */
  Pair("action", "updateLogin"),
  Pair("context", context)
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
pims.set(api: "pims.authentication.user", 
  parameters: [
  Pair("action", "updateLogin")
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}

Update Password #

To add a “update password” feature, implement the following api. Calling this API will prompt an External User-Agent (for native apps it can be the system browser) where the user will be able to update the password.

1
2
3
4
5
6
7
pims.set("pims.authentication.user",
  mapOf( /* parameters */
  Pair("action", "updatePassword"),
  Pair("context", context)
  )
) { message -> /* handle message */ }

1
2
3
4
5
6
pims.set(api: "pims.authentication.user", 
  parameters: [
  Pair("action", "updatePassword")
  ]
) { (message) in /* handle message */ }

1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}

Error 2301 #

After requesting any API, if an error 2301 is returned, your connection is lost. You should log out the user & log in again in order to fix this error.