Mobile SDK

iOS or Android

    Security - Device Enrollment & Account Managment

    Info: Stellantis Mobile SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available for now.

    Device Enrollement is required in order to use remote commands & vehicle status. Check out Service Activation Steps to get assistance accessing remote command.

    This page is a tutorial about Enrollment Process & Account Management:

    • First, the steps by steps describes the enrollment process of a device: steps with numbers 1️⃣ to 8️⃣.
    • Then, information about account management are available under letters A to D and steps with numbers 1️⃣, 2️⃣, 4️⃣-2️⃣, 6️⃣, 7️⃣.

    What is device enrollment? #

    Device Enrollment (aka Strong Authentication), provides a two factors authentication method (2FA). In order to perform device enrollment you’ll generate an SMS code that will be the seed for 2FA authentication.

    In order to perform device enrollement, you should first go through authentication. Then, you can start the enrollment process.

    At the end of this process, the device will be enrolled.

    Enrollment Process #

    They are 2 different methods to enroll a new device:

    • 🏎 Shortcut method: Starting from SDK version 2.1.0, the easiest way is to use EnrollmentWithPhoneNumber. In this case, you only need to perform step 1️ to step 4️·1 to enroll a new device. This method is not available if a phone number is already register.
    • 🐢 Full method: This enrollment process is longer since you need to go through all the steps from step 1 to step 8 going through step 4·2 (avoid step 4·1 in this case). Use this method in case:
      • You are using an SDK before version 2.1.0.
      • Some steps of the enrollment process have already been performed.

    The following schema details the steps to perform in order to enroll the device:

    1️⃣ Check enrollment status #

    First, you should check enrollment status, the device could be already enrolled.

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.account",
      mapOf( /* parameters */
      Pair("actionType", "strong"),
      Pair("type", "isDeviceActivated")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.account", 
      parameters: [
      "actionType": "strong",
      "type": "isDeviceActivated"
      ]
    ) { (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": {
        "isDeviceActivated": false
      }
    }
    

    false

    If the response result is true then the device is already enrolled!

    Otherwise, you should perform the enrollment process by going to step 2.

    2️⃣ Check account status #

    Before initiating the enrollment process, let’s check that the account is not blocked.

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.account",
      mapOf( /* parameters */
      Pair("actionType", "strong"),
      Pair("type", "isAccountBlocked")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.account", 
      parameters: [
      "actionType": "strong",
      "type": "isAccountBlocked"
      ]
    ) { (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": {
        "isAccountBlocked": false
      }
    }
    

    false

    In case the response is isAccountBlocked: 'AccountBlocked'/'PINBlocked', you need to remove all enrollments by going to step A.

    Info: the account could get blocked if the limit of enrolled device for an account is reached.

    If the account is not blocked (isAccountBlocked: 'NotBlocked') we can continue to step 3.

    3️⃣ Check phone number #

    To perform device enrollment, the account must have a registered trusted phone number.

    If it’s not the case, it should be added to the account because the phone number is used in order to receive an SMS Code.

    1
    2
    3
    
    pims.get("pims.authentication.trustedphonenumber"
    ) { message -> /* handle message */ }
    
    1
    2
    3
    
    pims.get(api: "pims.authentication.trustedphonenumber"
    ) { (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": {
        "phoneNumber": "0612345678"
      }
    }
    

    false

    If the response result value is trustedphoneNumber: null, then the account doesn’t have a trusted phone number.

    You should register a phone number (check out enrollment methods):

    If it does have a phone number value, then it’s possible to ask for an SMS Code, see step 5.

    4️⃣·1️⃣ Enrollment With Phone Number #

    This step is required only if you are following the shortcut method. It’s not part of the full method. Refer to enrollment methods description. This method is not available if a phone number is already register.

    In order to enroll the device and add a new phone number to the user account, an SMS code is required for verification.

    First, we should request to send an SMS code to the user phone number:

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "phoneNumberCertification"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.smscode", 
      parameters: [
      "type": "phoneNumberCertification",
      "phoneNumber": "0123456789",
      ]
    ) { (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
    }
    

    false

    The user should receive the SMS code on their phone. Let’s imagine the code is 2424 for the following request.

    Then we should perform the verification of the smsCode, phone number & pinCode. If the values are matching, the pinCode & phoneNumber are register for this account and the device is enrolled!

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    pims.set("pims.authentication.enrollment",
      mapOf( /* parameters */
      Pair("action", "enrollmentWithPhoneNumber"),
      Pair("pinCode", "424242"),
      Pair("smsCode", "2424"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    pims.set(api: "pims.authentication.enrollment", 
      parameters: [
      "action": "enrollmentWithPhoneNumber",
      "pinCode": "424242",
      "smsCode": "2424",
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false

    If the response is SUCCEEDED, the device is successfully enrolled!

    4️⃣·2️⃣ Register Trusted Phone Number #

    This step is required only if you are following the full method. It’s not part of the shortcut method. Refer to enrollment methods description.

    If the user doesn’t have a phone number, and you are using an SDK version after 2.1.0, you can use enrollment with phone number, it’s the easiest way to enroll a new device.

    In order to add a trusted phone number to the user account, an SMS code verification is required.

    First, we should request to send an SMS code to the user phone number:

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "phoneNumberCertification"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.smscode", 
      parameters: [
      "type": "phoneNumberCertification",
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false

    The user will receive an SMS Code on their phone, let’s imagine the code is 24242424 for the following request.

    Then we should perform SMS code verification & validate phone number:

    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "addPhoneNumber"),
      Pair("smsCode", "2424"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.smscode", 
      parameters: [
      "type": "addPhoneNumber",
      "smsCode": "2424",
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false

    If the response is SUCCEEDED, the phone number is registered!

    You can continue the enrollment process with step 5.

    5️⃣ Request enrollment SMScode #

    This step is required only if you are following the full method. It’s not part of the shortcut method. Refer to enrollment methods description.

    Once the user has a registered phone number, it’s possible to request an SMS code dedicated to device enrollment:

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "enrollment"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.smscode", 
      parameters: [
      "type": "enrollment"
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false

    The user should receive the SMS Code on his registered phone number, see step 4·1.

    In order to check the user enrollment, go to step 6.

    6️⃣ Check PIN Code #

    This step is required only if you are following the full method. It’s not part of the shortcut method. Refer to enrollment methods description.

    In addition to SMS code, enrollment require a PIN code. This PIN code is a short digit password.

    We should check if the account already have a registered PIN Code, to trigger this check, we need to pass the SMS Code requested in the previous step:

    1
    2
    3
    4
    5
    6
    7
    
    pims.set("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("action", "enrollment"),
      Pair("smsCode", "2424")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.set(api: "pims.authentication.smscode", 
      parameters: [
      "action": "enrollment",
      "smsCode": "2424"
      ]
    ) { (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": {
        "status": "AlreadyEnrolled"
      }
    }
    

    false

    If it has been previously enrolled ("status": "AlreadyEnrolled"), there is no need to add a new PIN code, the user should use the previous PIN code for step 8.

    Reset PIN Code: In case the user doesn’t remember the PIN Code, see step B for reset.

    Change PIN Code: In case the user needs to change the PIN Code, see step C for update.

    If the account doesn’t have a PIN Code, we should register a new PIN code, see step 7.

    7️⃣ Register new PIN code #

    This step is required only if you are following the full method. It’s not part of the shortcut method. Refer to enrollment methods description.

    In case this device has not been enrolled before for this account, we have to make the user register a new one:

    1
    2
    3
    4
    5
    6
    7
    
    pims.set("pims.authentication.enrollment",
      mapOf( /* parameters */
      Pair("action", "enroll"),
      Pair("pinCode", "1234"),
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.enrollment", 
      parameters: [
      "action": "enroll",
      "pinCode": "1234"
      "smsCode": "2424"
      ]
    ) { (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": {
        "status": "AlreadyEnrolled"
      }
    }
    

    false

    In this API, the parameter smsCode is only for iOS.

    Then, go to step 8.

    8️⃣ Request device enrollment & perform PIN Code validation #

    This step is required only if you are following the full method. It’s not part of the shortcut method. Refer to enrollment methods description.

    Once the user/device has a PIN code, it should be checked using the following command:

    1
    2
    3
    4
    5
    6
    7
    
    pims.set("pims.authentication.enrollment",
      mapOf( /* parameters */
      Pair("action", "enroll"),
      Pair("pinCode", "1234"),
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.enrollment", 
      parameters: [
      "action": "enroll",
      "pinCode": "1234"
      "smsCode": "2424"
      ]
    ) { (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": {
        "status": "AlreadyEnrolled"
      }
    }
    

    false

    In this API, the parameter smsCode is only for iOS.

    If the response result is SUCCEEDED, the device is successfully enrolled!

    Otherwise, if the response is FAILED and the error code is NOT 2317, we should retry PIN code verification by repeating this step 8.

    Finally, if the response is FAILED and the error code is 2317 the account is blocked, you should restart the enrollment process from start, step A.

    Account Management #

    Account management is a list of features that allow to interact with the user account. These features are APIs, they are part of the enrollment process (steps with numbers) or are not part of the regular enrollment process (steps with letters):

    A - Remove all enrollments #

    In some cases, you could need to reset all enrollments. In particular, this could happen if enrollment FAILED with error code 2317.

    In order to remove all enrollments, you need to request the following API:

    1
    2
    3
    4
    5
    6
    
    pims.set("pims.authentication.enrollment",
      mapOf( /* parameters */
      Pair("action", "remove")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    
    pims.set(api: "pims.authentication.enrollment", 
      parameters: [
      "action": "remove"
      ]
    ) { (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
    }
    

    false

    If it SUCCEEDED, then you can restart enrollment process from step 3.

    B - Reset PIN Code #

    In case the user doesn’t remember the PIN Code, you should suggest resetting the PIN Code.

    Enrollment Required: Reset PIN needs an active enrollment, you can check enrollment in step 1. If no enrollments are active, you need first to remove all enrollments (step A).

    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set("pims.authentication.pincode",
      mapOf( /* parameters */
      Pair("action", "reset"),
      Pair("pinCode", "4321"),
      Pair("smsCode", "2424")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.pincode", 
      parameters: [
      "action": "reset",
      "pinCode": "4321",
      "smsCode": "2424"
      ]
    ) { (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
    }
    

    false

    If the PIN Code reset is successful (response is SUCCEEDED), then you can continue the enrollment process from step 8.

    C - Update PIN Code #

    You can implement a feature allowing PIN Code updating.

    Enrollment Required: Reset PIN needs an active enrollment, you can check enrollment in step 1.

    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set("pims.authentication.pincode",
      mapOf( /* parameters */
      Pair("action", "update"),
      Pair("oldPIN", "7654"),
      Pair("newPIN", "0987")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.pincode", 
      parameters: [
      "action": "update",
      "oldPIN": "7654",
      "newPIN": "0987"
      ]
    ) { (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
    }
    

    false

    In case the user can not remember the old PIN Code, you can reset the PIN Code.

    D - Modify Phone Number #

    You can implement a feature allowing Phone Code modification.

    Check PIN Code first: Before trying to update the Phone Number, please follow step 3 in order to make sure the device has already a phone number.
    Enrollment Required: Reset PIN needs an active enrollment, you can check enrollment in step 1.

    1
    2
    3
    4
    5
    6
    7
    
    pims.get("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "modifyPhoneNumber"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    
    pims.get(api: "pims.authentication.smscode", 
      parameters: [
      "type": "modifyPhoneNumber",
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false

    The user will receive an SMS Code on their phone, then, you should use the following API to register the new phone number:

    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set("pims.authentication.smscode",
      mapOf( /* parameters */
      Pair("type", "modifyPhoneNumber"),
      Pair("smsCode", "2424"),
      Pair("phoneNumber", "0123456789")
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.authentication.smscode", 
      parameters: [
      "type": "modifyPhoneNumber",
      "smsCode": "2424",
      "phoneNumber": "0123456789"
      ]
    ) { (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
    }
    

    false