Pairing keys


Pairing keys

To enable multi-factor authentication via push notification on a mobile device, the user resource must have a mobile device and an application associated with its user ID. The association is implemented with a pairing key.

The pairing key endpoints provide operations to create, read, and remove pairing key resources associated with a specified user ID, mobile device and application. The examples below show common actions to manage pairing keys.

Pairing keys API operations

The pairing keys endpoints support the following operations:

For hands-on experience with the pairing keys API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Pairing key data model

Property Description
_links.self The URL of the pairing key resource.
_links.environment The URL of the environment resource.
_links.user The URL of the user resource.
id The resource ID.
environment.id The environment ID.
code The pairing key that the end users should use for pairing their device.
status The status of the pairing key. Valid values:
  • UNCLAIMED
  • CLAIMED
applications The collection of application IDs that can be used with this pairing key.
user.id The user ID.
createdAt The date this pairing key was created.
updatedAt The date this pairing key was updated.
expiresAt The date this pairing key expires.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.
500 Unexpected server error.

Endpoint examples

Get a pairing key status

The following sample shows the GET /environments/{envId}/users/{userId}/pairingkeys/{pairingKeyId} operation return information about the pairing key resource specified by its ID in the request URL.

curl -X "GET" "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617" \
-H 'Authorization: Bearer jwtToken'

The response data for the request looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3"
    }
  },
  "id": "30d03ef6-daa5-41a0-98c3-3b08d1a7c617",
  "environment": {
    "id": "f59504de-3c45-4a37-1234-d5ad75dfaaa0"
  },
  "code": "01646543025054",
  "status": "UNCLAIMED",
  "applications": [
    {
      "id": "5e81bba1-1234-457c-926a-aae0e8939109"
    }
  ],
  "user": {
    "id": "8f8a6354-1234-4430-964e-e10d4e5deed3"
  },
  "createdAt": "2019-07-16T19:03:34.658Z",
  "updatedAt": "2019-07-16T19:03:34.658Z",
  "expiresAt": "2019-07-18T19:03:34.657Z"
}

Create a pairing key

The POST /environments/{envId}/users/{userId}/pairingKeys operation adds a pairing key to the specified user resource.

Use the applications to provide a list of native application IDs that can be used with this pairing key. Leave applications as an empty collection to allow all available native applications in the environment to be used.

Only native applications that have bundleId or packageName, and are associated with pushCredentials are considered available in this context. Such applications should represent mobile applications that exist in the Apple or Google applications store.

curl -X "POST" "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617" \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "applications": [
    {
      "id": "5e81bba1-1234-457c-926a-aae0e8939109"
    }
  ]
}'

The response data for the request looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3"
    }
  },
  "id": "30d03ef6-daa5-41a0-98c3-3b08d1a7c617",
  "environment": {
    "id": "f59504de-3c45-4a37-1234-d5ad75dfaaa0"
  },
  "code": "01646543025054",
  "status": "UNCLAIMED",
  "applications": [
    {
      "id": "5e81bba1-1234-457c-926a-aae0e8939109"
    }
  ],
  "user": {
    "id": "8f8a6354-1234-4430-964e-e10d4e5deed3"
  },
  "createdAt": "2019-07-16T19:03:34.658Z",
  "updatedAt": "2019-07-16T19:03:34.658Z",
  "expiresAt": "2019-07-18T19:03:34.657Z"
}

Delete a pairing key

The following sample shows the DELETE /environments/{envId}/users/{userId}/pairingkeys/{pairingKeyId} operation to remove the pairing key specified in the request URL.

curl -X "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617" \
-H 'Authorization: Bearer jwtToken'

When the pairing key is removed successfully, the response returns a 204 Successfully deleted message.