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 his 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

Parameter Name Type Description
id String Pairing key.

The value returned from the call.

The customer server application should transfer this key to the end user.

The user will use this key for manual pairing.

pairingData String Free text.

PingID SDK doesn’t generate this value, and saves it as is.

The customer server application may use this field to build logic to connect the pairing key to a specific user or to a group of the users.

status enum Status of the pairing key.
  • NOT_CLAIMED

    This key is available, and the user may use it to pair his device.

  • USED

    This key is not available. A user has already successfully paired his device, using this paring key.

Available REST operations:

HTTP Method Description
POST Create PairingKey
GET Retrieve PairingKey
  • 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

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The unique identifier of the PingID SDK customer mobile application.

Create a pairing key: (POST) request body

Parameter Name Type Description
pairingData String Free text.

PingID SDK doesn’t generate this value, and saves it as is.

The customer server application may use this field to build logic to connect the pairing key to a specific user or to a group of the users.

Other fields are not relevant for the POST body request.
  • 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

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The unique identifier of the PingID SDK customer mobile application.
pairingKey String pairing key
  • 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"
        }