Users API


User management (creation, retrieval, updates and deletion of users) in PingID SDK is implemented using the Users REST API.

Parameters

Parameter Name Type Description
username String The user's assigned user name.

Must be unique in an account (tenant).

Up to 100 characters.

If there are special characters in the username:

  • On creation of the user, the username should be passed as is.
    For example, the username "User^" should be passed as "User^".
  • When the username is presented as part of a URL, it should be URL-encoded, with the following limitations:
    • The semicolon character ( ; ) is not supported.
    • The backslash character ( \ ) is not supported.
    • The username is permitted to contain a forward slash character ( / ), as long as it is not at the beginning or end of the username string or multiple consecutive forward slash characters within the username. For example:
      • Allowed: The username "User/test" and “User/test/one”.
      • Not allowed: The usernames "User//test", "/User", and "User/".
    • The forward slash character ( / ) in the username should not be encoded.
      For example, the username "User^" should be converted to "User%5E", but the username "User/^" should be converted to "User/%5E".
    • The username may not contain the following reserved keywords:
      • devices
      • smspairings
      • emailpairings
      • voicepairings
      • registrationtokens
      • authentications
      • authenticationtokens
      The list of reserved keywords may be extended in the future.
firstName String The user's first name.

Up to 64 characters.

lastName String The user's last name.

Up to 64 characters.

status enum

The user’s status in PingID SDK.

Valid values:

  • NOT_ACTIVE

    The user has no paired devices.

  • ACTIVE

    The user has at least one paired device for an application.

  • SUSPENDED

    The user is blocked from authentication.

  • UNKNOWN

    The scenario is missing some context input, for example, when checking for a user but not specifying the application. If the user is retrieved without the application context, PingID SDK cannot determine whether the user has any paired devices.

lastLogin Date The last date and time the user authenticated successfully.

Format:

ISO 8601 representation of a date (also as defined in RFC 3339), and should be presented according to the UTC time zone.

Dates presented in different time zones must be converted to UTC, or stored with a time zone identifier, so that date and time calculations can be applied.

Available REST operations

HTTP Method Description
POST Create a new user.
GET Retrieve a user.
PUT Update a user.
DELETE Delete a user.

Create a user: (POST)

The POST method is used whenever a new user is created in PingID SDK. The new user will still have to be paired with a mobile device before using PingID SDK.

Relative Path

/accounts/{accountId}/users

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.

Create a user: (POST) request:

Parameter Name Type Description
username String The user's assigned user name.

Must be unique in an account.

Up to 100 characters.

firstName String The user's first name.

Up to 64 characters.

Optional.

lastName String The user's last name.

Up to 64 characters.

Optional.

Other fields are not relevant for the POST request.
  • Create a user: (POST) request body example:
curl -X POST \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 -d '{ \
   "username": "john.smith", \
   "firstName": "John", \
   "lastName": "Smith" \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users'
  • Create a user: (POST) response body example:
{
  "devices": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.smith/devices"
  },
  "seendevices": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.smith/seendevices"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.smith"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "username": "john.smith",
  "firstName": "John",
  "lastName": "Smith",
  "status": "NOT_ACTIVE"
}

Retrieve a user: (GET)

The customer server application may retrieve a user’s details for display or user management purposes.

Relative Path

/accounts/{account_id}/applications/{application_id}/users/{username}

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
application_id String The ID of the PingID SDK customer mobile application.
username String The user's unique name in PingID SDK, per tenant.
expand String List of comma separated values.

Valid strings: self, account, seendevices, devices

Optional.

  • Retrieve a user: (GET) request example:
curl -X GET \
 --header 'Content-Type: application/json' \
 --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/users/john.galt'
  • Retrieve a user: (GET) response body example:
{
  "devices": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/devices"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt"
  },
  "seendevices": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/seendevices"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "username": "john.galt",
  "firstName": "John",
  "lastName": "Galt",
  "status": "ACTIVE"
}
  • Retrieve a user: (GET) request example, using the expand parameter:
curl -X GET \
 --header 'Content-Type: application/json' \
 --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/users/john.galt?expand=seendevices,devices'
  • Retrieve a user (GET): response body example, using the expand parameter:
{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "devices": [
    {
      "deviceType": "iPhone",
      "id": "128bd7a1-6b6a-4d37-128b-d7a16b6a4d37",
      "deviceFingerprint": "9Pzk1Y0YQBj5XwKcSBWm",
      "deviceNname": "iPhone 5S",
      "deviceRole": "primary",
      "enrollmentTime": 1489504195360,
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "bypassed": false
    }
  ],
  "seendevices": [
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "Y2NzeXMzNEtKSG1XQWhoZUFzRmE=",
      "deviceType": "Android",
      "deviceName": "samsung SM-G920F",
      "firstSeenAt": 1489504726009,
      "accessTime": 1489504726009,
      "ignored": false,
      "blocked": false
    }
  ],
  "username": "john.galt",
  "firstName": "John",
  "lastName": "Galt",
  "status": "ACTIVE"
}

Retrieve users by payload: (GET)

The customer server may identify the user or users, by using the mobile payload from a trusted mobile device. The mobile payload is generated from the mobile SDK component.

Relative Path

/accounts/{account_id}/applications/{application_id}/users

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
application_id String The ID of the PingID SDK customer mobile application.
expand String List of comma separated values.

Valid strings: account, application

Optional.

The payload query’s filter parameter is mandatory:

?filter=payload%20eq%20%<mobile payload>
  • Retrieve users by payload: (GET) request example:
curl -X GET --header 'Accept: application/json' \
'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users?filter=payload%20eq%20%<mobile payload>'
  • Retrieve users by payload: (GET) response body example:
{
  "users": [
    {
      "username": "john.galt",
      "firstName": "John",
      "lastName": "Galt",
      "status": "ACTIVE"
    }
  ]
}

Update a user’s first name and last name: (PUT)

The customer server may allow users to edit their own details, such as first and last name. The application’s user administrator may also want to update user details. In both these cases, the customer server calls the PUT method of the User resource.

Relative Path

/accounts/{account_id}/users/{username}/name

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.

Update a user: (PUT) request:

Parameter Name Type Description
firstName String The user's first name.
lastName String The user's last name.

Update a user: (PUT) request:

  • Update a user: (PUT) request example:
curl -X PUT \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 -d '{ \
   "firstName": "John", \
   "lastName": "Galt" \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/name'
  • Update a user: (PUT) response body example:
no content

Update a user’s SUSPENDED status: (PUT)

Use this operation to change the user’s status to SUSPENDED, across all applications in the organization, or take the user out of the SUSPENDED state.

Relative Path

/accounts/{account_id}/users/{username}/suspended

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.

Update a user: (PUT) request:

Parameter Name Type Description
suspended Boolean Whether to suspend the user.

Update a user: (PUT) request:

  • Update a user: (PUT) request example:
curl -X PUT \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 -d '{ \
   "suspended": true \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/suspended'
  • Update a user: (PUT) response body example:
no content

Delete a user: (DELETE) request

The administrator will initiate a delete user request for a user who must be removed from the PingID SDK authentication system, for instance, a user who is no longer a customer.

Relative Path

/accounts/{account_id}/users/{username}

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.
  • Delete a user: (DELETE) request example:
curl -X DELETE \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.doe'
  • Delete a user: (DELETE) respone body example:
no content