PingOne Recognize

External user ID

External user IDs let you set custom usernames for PingOne Recognize. Custom user IDs are typically easier to remember than globally unique identifiers (GUIDs) or similar structures.

You shouldn’t use personally identifiable information (PII) for custom user IDs, such as custom usernames, real names, or email addresses.

All endpoints require the X-Api-Key header for authentication, which should contain your PingOne Recognize authorization key. For help, contact Support.

For customers using the Authentication Service (which supports IDV Bridge SaaS and WebSDK), the External User ID documented on this page is mapped automatically to the Username in that service for ease of use.

POST /users/{userId}/external-user

Create an external user

Associate an external user ID with an existing Keyless user. A user can only have one external user associated at a time.

Path parameters

Name Type Description

userId required

string (HEX)

Uppercase HEX string representing the user ID

Request body — application/json

Field Type Description

externalUserId required

string

Your system’s identifier for this user

Responses

Status Description

201

ExternalUserResponse — contains sdkCustomerId, userId, externalUserId, createdAt, updatedAt

400 / 401 / 404 / 406 / 409 / 415

Standard error responses

500

Internal server error

Example

Request

POST /v2/users/A1B2C3D4E5F6/external-user
X-Api-Key: your-api-key
Content-Type: application/json

{
  "externalUserId": "custom-name@example.com"
}

Response 201

{
  "sdkCustomerId": 42,
  "userId": "A1B2C3D4E5F6",
  "externalUserId": "custom-name@example.com",
  "createdAt": "2025-05-21T10:00:00.000",
  "updatedAt": "2025-05-21T10:00:00.000"
}

PATCH /users/{userId}/external-user

Update an external user

Modify the external user associated with a Keyless user. This operation is idempotent and safe to retry.

Path parameters

Name Type Description

userId required

string (HEX)

Uppercase HEX string representing the user ID

Request body — application/json

Field Type Description

externalUserId required

string

The new external user ID to associate

Responses

Status Description

200

ExternalUserResponse — updated external user data

400 / 401 / 404 / 406 / 415

Standard error responses

500

Internal server error

Example

Request

PATCH /v2/users/A1B2C3D4E5F6/external-user
X-Api-Key: your-api-key
Content-Type: application/json

{
  "externalUserId": "custom-name@example.com"
}

Response 200

{
  "sdkCustomerId": 42,
  "userId": "A1B2C3D4E5F6",
  "externalUserId": "custom-name@example.com",
  "createdAt": "2025-05-21T10:00:00.000",
  "updatedAt": "2025-05-21T11:30:00.000"
}

DELETE /external-users/{externalUserId}

Delete an external user

The external user ID is case-sensitive. Returns a success response even if the external user doesn’t exist.

Path parameters

Name Type Description

externalUserId required

string

Customer-meaningful user ID. Case-sensitive

Responses

Status Description

204

External user deleted (also returned if user didn’t exist)

400 / 401 / 404 / 406

Standard error responses (404 indicates endpoint not found, not user not found)

500

Internal server error

Example

Request

DELETE /v2/external-users/custom-name@example.com
X-Api-Key: your-api-key

Response 204

// No response body

GET /external-users/{externalUserId}/users

Get Keyless users by external ID

Get all Keyless users associated with the given external user ID. Returns an empty list if none are found. The external user ID lookup is case-insensitive.

Path parameters

Name Type Description

externalUserId required

string

Customer-meaningful user ID. Case-insensitive for this lookup

Responses

Status Description

200

Array of UserResponse objects — each with userId, biometricPublicSigningKey, createdAt, updatedAt. Empty array if no users found

400 / 401 / 404 / 406 / 409

Standard error responses

500

Internal server error

Example

Request

GET /v2/external-users/custom-name@example.com/users
X-Api-Key: your-api-key

Response 200

[
  {
    "userId": "A1B2C3D4E5F6",
    "biometricPublicSigningKey": "BJSafl+GrMLT2y43...",
    "createdAt": "2025-01-10T08:00:00.000",
    "updatedAt": "2025-05-21T10:00:00.000"
  }
]