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

Parameter Name Description
id The authentication token ID. This ID should be used for polling the authentication token status.
tokenSchemeUri Generated.
  • If the application scheme is defined in the admin web portal, the tokenSchemeUri has the value:
    <app scheme>://pingidsdk?authentication_token=<generated token>.
  • If the application scheme is not defined, the tokenSchemeUri has the value:
    pingidsdk?authentication_token=<generated token>
    Display this link if you detect that the user accesses from a mobile browser. In the case of web access, embed the tokenSchemeUri in a QR code image.
username Optional.
  • The authentication token can be created in a specific username context.
  • Only the specified user can use the token.
  • The user may not be suspended and must have at least one mobile app paired. In this case, the server returns 400 error code ("bad request"). The internal error code will be one of the following:
    • USER_DISABLED: When the user is suspended.
    • USER_NOT_ACTIVE: When the user has no devices at all.
    • NO_MOBILE_ACTIVE_DEVICES: When the user has no active mobile devices.
  • The username can also be generated. Once the user is known, the username parameter will be populated with the user's name.
deviceId Generated.
The ID of the device that successfully used the token.
userApprovalRequired Optional.
  • Indicates whether the mobile should verify that the user approves the authentication with the scanned token.
  • The PingID SDK server expects to receive a user input of either approval or denial from the mobile.
  • The default is false.
webUserSelection Indicates whether the web or mobile should select the user, if the application on the device that scanned the token is shared between multiple users.
By default, the mobile selects the user.
users Generated.
The users list.
  • When the application on the device that scanned the QR code is shared by several users, “users” is populated with the user list.
  • Each element in the list is a user resource.
  • If the status is PENDING_WEB_USER_SELECTION, the customer server should select the user from this list, depending on the value of “webUserSelection”.
  • The list may contain suspended users. However, the web is not allowed to select a suspended user.
  • Once the web selects the user, it should call Update the authentication resource: (PUT).
  • If there is only one user, the list will be populated with that user.
status Generated.

Possible values:

  • NOT_CLAIMED: Initial value.
  • CLAIMED: The authentication token is successfully claimed.
  • CANCELED: The authentication token is canceled.
    Use the DELETE verb to cancel an authentication token.
    You can cancel an authentication token for any reason.
  • IN_PROGRESS: The authentication token is in progress (statusReason field indicates the current state).
  • PENDING_WEB_USER_SELECTION: The customer server needs to select the user. This status is expected only if:
    • There is more than one user paired to the device.
    • webUserSelection is set to true.
  • EXPIRED: The authentication token is expired.
    • A user approval is required (userApprovalRequired = true), and the user hasn't replied within 3 minutes after successfully scanning the QR code.
    • Multiple users share the mobile app account, and the user who initiated the QR code authentication hasn't selected a user from the users list within 3 minutes after successfully scanning the QR code.
  • DENIED: The user denied authentication after scanning.
statusReason Generated.
An explanation describing the cause of the status.
  • When the status is CLAIMED:
    • NONE: Default.
    • PUSH_SUCCEED: An extra push verification was required and succeeded.
    • PUSH_FAILED: An extra push verification was required and failed.
    • PUSHLESS: An extra push verification was required but was not sent, since the device is pushless.
  • When the status is IN_PROGRESS:
    • PENDING_MOBILE_USER_SELECTION: The mobile selects the user, since there is more than one user paired to the device.
    • PENDING_PUSH_VERIFICATION: An extra push verification is performed.
    • PENDING_USER_APPROVAL: Following an extra push verification, authentication with the token is pending user approval, until the user approves or denies the authentication request.
clientContext Any data that the customer server should pass to the application.
For example, in this field you can pass the context in which the QR code was generated (login, transaction approval, and so forth).
pushMessageTitle The push message title's text, for a regular push (unless the device is pushless) sent only when the web selects the user (webUserSelection == true) and user approval is required (userApprovalRequired == true).
You can customize the push message title.
pushMessageBody The push message body text, for a regular push (unless the device is pushless) sent only when the web selects the user (webUserSelection == true) and user approval is required (userApprovalRequired == true).
You can customize the push message body.

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'
  • 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)