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.

Note: PingID SDK expects a unique user identifier (username) for each user. The customer server design should determine the type of identifier, whether it is a username or UUID that is mapped to a user. PingID SDK maintains a history of each user. If a user is deleted and later recreated, their blocked and seen devices are restored.

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.

Note: Optional query parameter: expand:

This parameter allows you to receive information about resources related to this resource, for example, a user might have linked devices. In this case, one might ask for a user resource, using the expand parameter to also retrieve the user’s devices.

When you send request without the expand parameter in the body of a response, you will see different names of resources and references to them. You can use these references to retrieve information about these kinds of resources, or you may use the expand parameter.

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