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"
}