RegistrationToken API


Automatic pairing:

Registration of a device behind the scenes means that during user authentication, a customer server communicates with PingID SDK to generate a token. This token allows pairing a device to the user. The user is not aware of this, and is not required to type or scan anything.

Automatic pairing has the advantage of good user experience: PingID SDK works behind the scenes, with minimal interaction with a user.

This section describes the implementation of automatic pairing.

RegistrationToken representation

Parameter Name Type Description
payload String The token string generated by the PingID SDK component in the customer mobile application.

Optional.

id String The value returned from the call.
pairingKey String In cases of manual pairing, the customer server application should provide this key.

Optional.

ignoreValidation boolean Determine whether an active user requires an existing trusted device (usually the user's primary device) to verify permission to register the new device. This option permits pairing of a user device for an active user without verification from the other user device.
  • false (default):
    Requires verification from an existing trusted device in order to pair a new user device. This is the recommended best practice.
  • true:
    Bypasses verification from an existing trusted user device, and permits creation of the registration token for pairing the new device.
status String The registration token status returned from the call. Possible values:
  • not_claimed:
    The registration token has not been used yet.
  • claimed:
    The registration process is in progress, and the registration token is in use.
  • active:
    The registration process has completed, and the device is successfully paired using this registration token.
  • invalidated:
    The registration token is invalid for registration, because the user started a new registration for the same application, with a new registration token.

Available REST operations

HTTP Method Description
POST Create RegistrationToken
GET Retrieve RegistrationToken

Authorization

All requests require authorization of the server. For further details, refer to Signatures in PingID SDK.

Create RegistrationToken (POST)

If the user is not active, the customer server application should create the RegistrationToken resource. This resource is used to pair the user’s mobile device to the user account in the PingID SDK server.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/registrationtokens

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The ID of the PingID SDK customer mobile application.
username String The user's unique name in PingID SDK, per tenant.

Request Body

Parameter Name Type Description
payload String The string generated by the PingID SDK component in the customer mobile application.

Required.

pairingKey String In cases of manual pairing, the customer server application should provide this key

Optional.

Other fields are not relevant for the POST request.
  • Create RegistrationToken: (POST) request example:

    curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header 'Authorization: PINGID-HMAC=<JWT>' -d '{ "payload": "eyJhcHBJZCI6IjQ5YjllZDM3LTMxY2UtNDg4Zi05YzQ0LTFmZTFlZDk1Zjc1NiIsImRldmljZUZwIjoiVjBVNVoyNXRNRTR6UlV3MFVsRk1WM2d3UjBrXHUwMDNkIiwiZGV2aWNlTmFtZSI6InNhbXN1bmcgU00tRzkyMEYiLCJkZXZpY2VUeXBlIjoiQW5kcm9pZCIsInJhbmRvbSI6IjU0OTE0MTYzODcxNTMzMTUxIn0K" }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/registrationtokens'
  • Create RegistrationToken: (POST) response example:

    {
      "application": {
        "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756"
      },
      "self": {
        "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/registrationtokens/537825544881"
      },
      "id": "537825544881",
      "payload": "eyJhbGciOiJSUzI1NiJ9.eyJhY3RpdmF0aW9uQ29kZSI6IjUzNzgyNTU0NDg4MSIsInBhaXJpbmdTdGF0dXMiOjMsInBhaXJpbmdRdWVzdGlvbnMiOlsiSVNfUFJJTUFSWSIsIklTX1RSVVNURUQiLCJJR05PUkUiXX0.D7knlZe8mgDsPkyhyIZUo-dGJrgIuNxdt0zfobNtv4SUtuPNuVb8ESPoTYGQs8uLWxTdu581hqlWdxwyeJEe0sya2yqXzpx5YBQNeI6wJrYmqg48C69_ZE4MxyObpm2XeQKNFA2seh9NmPpQ4_GYywL_i0JfvmFK0ThMOnVXpFdPvGeRagCgJ5yciohb8iXK_9vqHGWrqzsXjjl40_w8jUJAzorDz7ktSo0CEZwC3bDxvDSjM8T4eOvfv3BzMazXdAiOPgSAxHgwVTsblOD6hW2TR8wWYz_cKnr6CcPgPSbLffX1qfW4dod7NMKHclGKJAG4XFkeS2kO-o0BU6KjOg"
    }

Retrieve RegistrationToken (GET)

To retrieve a RegistrationToken resource, the customer server application should call the GET method of this endpoint.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/registrationtokens/{registrationtokenId}

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The ID of the PingID SDK customer mobile application.
username String The user's unique name in PingID SDK, per tenant.
registrationtokenId String The ID of the RegistrationToken.
  • Retrieve a RegistrationToken: (GET) request example:

    curl -X GET 
    --header 'Accept: application/json' \
    --header 'Authorization: PINGID-HMAC=<JWT>' \
    'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/registrationtokens/537825544881'
  • Retrieve a RegistrationToken: (GET) response example:

    {
      "self": {
        "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/registrationtokens/537825544881"
      },
      "user": {
        "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a/users/john.galt"
      },
      "account": {
        "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a"
      },
      "id": "537825544881",
      "ignoreValidation": false,
      "status": "active"
    }