Authenticate with QR code (authentication token)

The Authenticate with QR code (authentication token) API is similar to the central Authentication API, and is used for authentication of users and their devices.

The authentication tokens endpoint enables you to authenticate a user by scanning a QR code, or in case of mobile access, by clicking on a link. The flow follows the following general steps:

1. Create an authentication token, which will also generate the authentication token ID.
2. Embed the token in a QR code image. Optionally, create a link if the user access is from a mobile browser.
3. Poll the authentication token using the authentication token ID. Once the user successfully used the token, either by scanning successfully the QR code or by clicking on the link, the returned token status will be “CLAIMED”.

Refer to the descriptions of status and statusReason for the full list of the authentication token statuses and status reasons.

Relative path:

/accounts/{account_id}/applications/{application_id}/authenticationtokens

QR code authentication representation

Start a new QR code authentication (POST)

To start a new authentication, the customer server initiates a POST request to the authentication tokens endpoint in the PingID SDK service. The authentication token is created.

After 30 minutes, the authentication token is automatically deleted.

Relative Path

/accounts/{account_id}/applications/{application_id}/authenticationtokens

Request Body

Following is an example of a QR code authentication:

• Start a new authentication: (POST) request body example:

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
    "clientContext": "transaction approval", \
    "pushMessageTitle": "push title example", \
    "pushMessageBody": "push message example", \
    "userApprovalRequired": true, \
    "webUserSelection": false \
  }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens'

  Note: You can add “username” to the request body, if you want the authentication token to be bound to a specific user.

• Start a new authentication: (POST) response body example:

  "application": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a"
  },
  "self": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ"
  },
  "id": "webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ",
  "tokenSchemeUri": "pingidsdksample://pingidsdk?authentication_token=70685d4d-e2e8-4984-a612-7206f95546b9",
  "status": "NOT_CLAIMED",
  "statusReason": "NONE",
  "clientContext": "transaction approval",
  "pushMessageTitle": "push title example",
  "pushMessageBody": "push message example",
  "userApprovalRequired": true,
  "webUserSelection": false
  }

Retrieve a QR code authentication (GET)

To retrieve a QR code authentication token, the customer server application should call the GET method of this endpoint.

Relative Path

/accounts/{account_id}/applications/{application_id}/authenticationtokens/{id}

Following is an example of retrieving a QR code authentication:

• Retrieve an authentication: (GET) request body example:

  curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ'

• Retrieve an authentication: (GET) response body example:

  {
    "application": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a"
    },
    "self": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ"
    },
    "account": {
  "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4"
    },
    "id": "webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ",
    "tokenSchemeUri": "pingidsdksample://pingidsdk?authentication_token=70685d4d-e2e8-4984-a612-7206f95546b9",
    "status": "NOT_CLAIMED",
    "statusReason": "NONE",
    "clientContext": "transaction approval",
    "pushMessageTitle": "push title example",
    "pushMessageBody": "push message example",
    "userApprovalRequired": true,
    "webUserSelection": false
  }

Update the authentication resource: (PUT)

To update a QR code authentication token username, the customer server application should call the PUT method of this endpoint.

Updating the username using this endpoint is only relevant if:

1. The mobile app that scanned the QR code is shared with several users.
2. The web is responsible for user selection. By default, the mobile is responsible for the user selection.

The available users are returned in the “GET” authentication token response, in the “users” field.

Relative Path

/accounts/{account_id}/applications/{application_id}/authenticationtokens/{id}/username

Request Body

Following is an example of an update of a QR code authentication:

• Update the authentication token: (PUT) request example:

  curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
     "username": "user1" \ 
   }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/webs_qVpHk0C_PBVrIzPScDGcWErdPm-H2DKe9b3P8oqRcety5yzZvTTxAhScNoHnnwfsWpS31ij5tfBEUyOl8QRG5A/username'

• Update the authentication token: (PUT) response example:

  {
    "self": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/{authenticationTokenId}"
    },
    "account": {
      "href": "https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4"
    },
    "id": "webs_qVpHk0C_PBVrIzPScDGcWErdPm-H2DKe9b3P8oqRcety5yzZvTTxAhScNoHnnwfsWpS31ij5tfBEUyOl8QRG5A",
    "tokenSchemeUri": "pingidsdksample://pingidsdk?authentication_token=d3172745-312c-4cf6-9aa9-6911939184df",
    "status": "CLAIMED",
    "statusReason": "PUSHLESS",
    "username": "user1",
    "users": [
      {
        "username": "user1",
        "firstName": "user first name",
        "lastName": "user last name",
        "externalName": null,
        "status": "ACTIVE"
      }
    ],
    "deviceId": "3c377076-47b6-4339-3c37-707647b64339",
    "clientContext": "transaction approval",
    "pushMessageTitle": "push title example",
    "pushMessageBody": "push message example",
    "userApprovalRequired": false,
    "webUserSelection": true
  }

Cancel the authentication: (DELETE)

The DELETE authentication method should be used to cancel authentication with an authentication token. The cancellation can be done at any stage, as long as the authentication token exists and its status is not “CLAIMED” or “CANCELED”.

Relative Path

/accounts/{account_id}/applications/{application_id}/authenticationtokens/{id}

Following is an example of a cancellation of a QR code authentication:

• Cancel the authentication: (DELETE) request example:

  curl -X DELETE --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/authenticationtokens/webs_3DrzYP90K8WJipY2hEvs7v77cW0UYvprLsJpydJ3AJ3dnlvJdtBrELrDHbwUp8DCoFyYszviNsQpRpim5gidsQ'

• Cancel the authentication: (DELETE) response example:

  no content (204)