PairingKey API

Manual pairing is relevant for a user’s first device, requiring interaction with the user. The end user should enter or scan a previously provided pairing key in the customer mobile application, on their mobile device.

Manual pairing allows the customer mobile application more implementation options than automatic pairing. Manual pairing offers the following capabilities:

• Separation of the registration and authentication processes.
• Management of the logic to determine what the user’s pairing key should match. The customer mobile application logic may choose that the pairing key should match one user, or a group of users.

Manual pairing requires development of new flows between the customer mobile application and the customer server.

This section describes the implementation of manual pairing.

PairingKey representation

Available REST operations:

• Authorization

  All requests require authorization of the PingID SDK server. Refer to Signatures in PingID SDK for further details.

• Create a pairing key

  There are two options to create a pairing key:

  • Application scope: The customer server application should use the relative path in the application scope, to create a pairing key within the scope of a specific application:

    /accounts/{accountId}/applications/{applicationId}/pairingkeys

    When the customer server application creates a pairing key in the scope of application, the specific application of the tenant may use this pairing key.

  • Organization scope: The customer server application should use the relative path in the organization scope, to create a pairing key within the scope of a specific organization:

    /accounts/{accountId}/pairingkeys

    When the customer server application creates a pairing key in the scope of organization, any application in the specific tenant may use this pairing key.

Create a pairing key: (POST)

Parameters

Create a pairing key: (POST) request body

• Create a pairing key: (POST) request example

  curl -X POST \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json'
   --header 'Authorization: PINGID-HMAC=<JWT>' -d '{ "pairingData": "[\"john.smith\", \"dagny.taggart\"]" }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/pairingkeys'

• Create a pairing key: (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/pairingkeys/349666846915"
  },
  "account": {
  "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "id": "349666846915",
  "pairingData": 
  "[\"john.smith\", \"dagny.taggart\"]",
  "status": "NOT_CLAIMED"
  }

Retrieve a pairing key: (GET)

There are 2 options to retrieve an existing pairing key:

• In the scope of a specific application:

  Use the application’s relative path to get the pairing key in the application’s scope:

  /accounts/{accountId}/applications/{applicationId}/pairingkeys/{pairingKey}

  If the pairing key was created in the application’s scope, the PingID SDK server allows to the customer server application to receive it in the scope of the specific application. In the organization’s scope, PingID SDK will return the NOT_FOUND error.

• In the scope of the organization:

  Use the organization’s relative path to get the pairing key in the organization’s scope:

  /accounts/{accountId}/pairingkeys/{pairingKey}

  If a pairing key value was created in the organization’s scope, the PingID SDK server allows the customer server application to receive it in both the organization and application scopes.

Parameters

• Application scope:

  • Retrieve a pairing key: (GET) request example, created in an application scope.

  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/pairingkeys/349666846915'

  • Retrieve a pairing key: (GET) response example, created in an application scope.

  {
  "self": {
  "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/pairingkeys/349666846915" 
  },
  "account": {
  "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "id": "349666846915",
  \"pairingData": "[\"john.smith\", \"dagny.taggart\"]",
  "status": "NOT_CLAIMED"}

• Organization scope:

  • Retrieve a pairing key: (GET) request example, created in an organization scope.

    curl -X GET \
     --header 'Accept: application/json' \
     --header 'Authorization: PINGID-HMAC=<JWT>' \
    'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/pairingkeys/191073927231'

  • Retrieve a pairing key: (GET) response example, created in an organization scope.

    {
    "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/pairingkeys/191073927231"
    },
    "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
    },
    "id": "191073927231",
    "pairingData": "yury",
    "status": "NOT_CLAIMED"
    }

  • Retrieve a pairing key, without the applicationId for a pairing key, created in an organization scope.

    • Retrieve a pairing key: (GET) request example, without the applicationId for a pairing key, created in an organization scope.

      curl -X GET \
       --header 'Accept: application/json' \
       --header 'Authorization: PINGID-HMAC=<JWT>' \
      'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/pairingkeys/349666846915'

    • Retrieve a pairing key: (GET) response example, without the applicationId for a pairing key, created in an organization scope.

      {
      "message": "pairingKey 349666846915 not found",
      "id": "webs_046b4007-250e-4871-a3c7-f6a26883c88f",
      "target": "pairingKey",
      "details": [],
      "code": "NOT_FOUND"
      }