PingOne Directory API

The PingOne Directory provides a hosted directory service that developers can use to store user authentication and profile data. The directory interface uses the System for Cross-Domain Identity Management (SCIM) v1.1 open standard protocol. SCIM provides both a defined schema for user representation as well as a RESTful API for performing user and group CRUD actions (Create, Read, Update and Delete).

 

Register for a PingOne account

Before you integrate PingOne Directory into your application, your company will need to set up a PingOne account. If you do not already have a PingOne account, you can register for a PingOne developer trial.

To enable the PingOne Directory in your PingOne account, you need to set the Identity Bridge to use the PingOne Directory.

 

PingOne Directory administrator account

Each PingOne account must have at least one user with administrator rights. PingOne Directory users can be managed by an administrator with Global Admin or Directory Admin permissions.

 

Account security settings

The directory API uses HTTP Basic authentication (RFC 2617). You'll need to use the API credentials registered for your account to build the HTTP Basic authorization header. You'll find your API credentials (the Client ID and API Key) on the Setup > Directory Settings > API Credentials page in the PingOne admin portal. To build the HTTP Basic authorization header follow these steps (replacing the sample API credentials with those for your account): 

Client ID 1234-aaaa-bbbb-5678
API Key eXJzbmVha3kh 

 

  1. Join the "Client ID" and "API Key" with a colon (:):
    1234-aaaa-bbbb-5678:eXJzbmVha3kh

  2. Base64 encode this value:
    MTIzNC1hYWFhLWJiYmItNTY3ODplWEp6Ym1WaGEza2g=

  3. Add a HTTP header with the name "Authorization" and the value "Basic " + the base64 encoded credentials, resulting in the following header included in each request to the Directory API:
    Authorization: Basic MTIzNC1hYWFhLWJiYmItNTY3ODplWEp6Ym1WaGEza2g=

Directory Actions

The SCIM protocol uses the REST concept to define the actions a SCIM Consumer can perform on a resource managed by the PingOne Directory (a SCIM Service Provider). These actions can be performed against User resources and Group resources in the directory:

HTTP Verb Action
GET Reads / queries for a resource (or resources) from the Service Provider
POST Creates a new resource at the Service Provider
PUT Updates an existing resource. This action requires the entire resource provided in the body, making it more like a replace than an update.
PATCH Updates an existing resource with changes to multi-valued attributes (such as group membership)
DELETE Deletes a resource at the Service Provider

 

User Resources

The User resource represents a user or identity profile in the directory. The PingOne Directory supports the following SCIM schema's:

  • SCIM Core Schema (urn:scim:schemas:core:1.0)
  • SCIM Enterprise User Schema (urn:scim:schemas:extension:enterprise:1.0)
  • PingOne Schema (urn:scim:schemas:com_pingone:1.0)

A user resource can be queries by the following API endpoint:

https://directory-api.pingone.com/api/directory/user


Note: For directories located in the European region, the API host is https://directory-api.pingone.eu

 

User Actions

In addition to the core SCIM actions (Create, Read, Update, Delete), the PingOne directory also supports the following actions for users:

 

Group Resources

Groups are represented by the SCIM group object. Groups can contain either group or user resources as members allowing for nested group support. The group object also supports the PATCH operation for group membership changes.

A group resource can be queried by the following API endpoint:

https://directory-api.pingone.com/api/directory/group


Note: For directories located in the European region, the API host is https://directory-api.pingone.eu

 

Group Actions

In addition to the core SCIM actions (Create, Read, Update, Delete), the PingOne directory also supports the following actions for groups:

 

 

Technical description

The PingOne directory leverages the SCIM v1.1 API to perform resource CRUD actions (Create, Read, Update, Delete). More information about the SCIM v1.1 API can be found in the SCIM developers guide.

 

Creating the requests

A request consists of using the appropriate verb to call the SCIM resource endpoint (i.e. User or Group) when modifying a resource directly, perform the action on the resources location URL (the is the "location" attribute for a given resource).

As an example, the following POST action to the user endpoint will create a new user in the directory:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"schemas":["urn:scim:schemas:core:1.0"],
"userName":"marcher",
"password":"2Federate",
"active":true,
"name":{ "familyName":"Archer", "givenName":"Meredith" },
"emails": [ { "type": "work", "value": "meredith.archer@pingdevelopers.com” }]
}' \
https://directory-api.pingone.com/api/directory/user

 

Handling responses

In most scenarios, the API response will be the complete SCIM representation of the resource (i.e. a DELETE action will not return a SCIM object). An example of a successful API response for a create request is included:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0": {
"createTimeStamp":1429123454227,
"accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
"lastModifiedTimeStamp":1429123454227,
"directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
"state":"ACTIVE" },
"name":{
"familyName":"Archer",
"givenName":"Meredith" },
"userName":"marcher",
"active":true,
"emails":[{
"value":"meredith.archer@pingdevelopers.com",
"type":"work" }],
"meta":{
"lastModified":"2015-04-15T12:44:14.227-06:00",
"location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{
"display":"Users",
"value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}

 

Handling Errors

Errors use regular HTTP response cods to return an error message to the caller. These will be in the 400-499 range and relate directly to the request (for example if a resource is not found during an update, a 404 (NOT FOUND) error will be returned).

 

Creating a User

A user create is performed by a POST operation. The JSON representation of the user (according to the SCIM schema) is POSTed to the User endpoint.

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"schemas":["urn:scim:schemas:core:1.0"], 
"userName":"marcher", 
"password":"2Federate",
"active":true,
"name":{ "familyName":"Archer", "givenName":"Meredith" },
"emails": [ { "type": "work", "value": "meredith.archer@pingdevelopers.com” }]
}' \
https://directory-api.pingone.com/api/directory/user?option=DEFAULT_USER_GROUP

If you specify the DEFAULT_USER_GROUP option, the user is added to the directory Users group (the default group for new users). 

A successful request will result in a HTTP 200 OK response and the JSON representation of the user that was just created:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0": {
  "createTimeStamp":1429123454227,
  "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
  "lastModifiedTimeStamp":1429123454227,
  "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
  "state":"ACTIVE" },
"name":{
  "familyName":"Archer",
  "givenName":"Meredith" },
"userName":"marcher",
"active":true,
"emails":[{
  "value":"meredith.archer@pingdevelopers.com",
  "type":"work" }],
"meta":{
  "lastModified":"2015-04-15T12:44:14.227-06:00",
  "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{
  "display":"Users",
  "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}

In the response, the “id” attribute contains the unique identifier for this user in the PingOne Directory. To modify this user (such as adding them to other groups), you will reference them via the "id" attribute value. The “location” attribute contains the full resource URL that you will use to manipulate the resource in the next sections.

 

Creating a Group

Creating a group is a similar process, performing a POST operation against the Group endpoint:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d ' {
"schemas":["urn:scim:schemas:core:1.0"],
"displayName":"Software Developers" }' \
https://directory-api.pingone.com/api/directory/group

A successful request will result in a HTTP 200 OK response and the JSON representation of the group that was just created:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"id":"7c513a7e-55d4-441c-858c-7329e6268084",
"displayName":"Software Developers",
"schemas":[
  "urn:scim:schemas:core:1.0",
  "urn:scim:schemas:com_pingone:1.0" ],
"meta":{
  "lastModified":"2015-04-16T10:08:22.324-06:00",
  "created":"2015-04-16T10:08:22.324-06:00",
  "location":"https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-
858c-7329e6268084" },
"urn:scim:schemas:com_pingone:1.0": {
  "createTimeStamp":1429200502324,
  "lastModifiedTimeStamp":1429200502324,
  "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
  "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137"}
}

GET Operation

You can retrieve a specific user's directory profile by:

  • Querying for the user by performing a GET operation against the User endpoint
  • Retrieving the user by performing a GET operation against the User resource directly

To query for a user you will use the SCIM query language to form your query, refer to the SCIM specifications for more information. To retrieve our recently created user we will use the filter: username eq “marcher” which will be urlencoded and appended to the User endpoint as the “filter” parameter:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user?filter=userName%20eq%20%22marcher%22

or by performing a GET directly on the user resource (which is defined in the “location” attribute in the “meta” section of the user record). Both the example above and this one will return the same result. So, to retrieve Meredith’s profile directly I can also perform the following command:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

A successful request will result in a HTTP 200 OK response and the JSON representation of the user:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[
  "urn:scim:schemas:core:1.0",
  "urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0":{
  "createTimeStamp":1429123454227,
  "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
  "lastModifiedTimeStamp":1429123454227,
  "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
  "state":"ACTIVE" },
"name":{
  "familyName":"Archer",
  "givenName":"Meredith" },
"userName":"marcher",
"active":true,
"emails":[{
  "value":"meredith.archer@pingdevelopers.com",
  "type":"work" }],
"meta":{
  "lastModified":"2015-04-15T12:44:14.227-06:00",
  "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-
746472c4f1f7",
  "created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{
  "display":"Users",
  "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}

Additionally, you can retrieve the details for all users in the directory. In this case, don't specify a user filter and set the startIndex and count parameters to determine the number of users to return:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user?sortBy=userName&sortOrder=ascending&startIndex=1&count=100

Where startIndex is the index at which user retrieval will begin, and count is the number of users to return per page. The maximum count value is 1,000. If you need to retrieve more than 1,000 users, you'll need to use multiple calls, increasing the startIndex value by 1,000 each time until all users are returned.

PUT Operation

Resource modifications are performed using a PUT operation returning the entire user profile with the changes applied. For example, to add a “title” to Meredith’s record I will take the contents of a GET request, add in the title attribute and PUT it back to Meredith’s User resource location.

Note: Some attributes are not enabled by default in PingOne Directory. You may need to enable the attribute in the PingOne administration console before modifying the record.

curl -v –X PUT --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[ "urn:scim:schemas:core:1.0", "urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0":{
  "createTimeStamp":1429123454227,
  "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
  "lastModifiedTimeStamp":1429123454227,
  "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
  "state":"ACTIVE" },
"name":{ "familyName":"Archer", "givenName":"Meredith" },
"userName":"marcher",
"title":"Software Developer",
"active":true,
"emails":[{"value":"meredith.archer@pingdevelopers.com","type":"work" }],
"meta":{
  "lastModified":"2015-04-15T12:44:14.227-06:00",
  "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{ "display":"Users", "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}' \
https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

A successful response from a modify operation is the user profile returned in full:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[
  "urn:scim:schemas:core:1.0",
  "urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0":{
  "createTimeStamp":1429123454227,
  "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
  "lastModifiedTimeStamp":1429123456527,
  "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
  "state":"ACTIVE" },
"name":{
  "familyName":"Archer",
  "givenName":"Meredith" },
"userName":"marcher",
"title":"Software Developer",
"active":true,
"emails":[{
  "value":"meredith.archer@pingdevelopers.com",
  "type":"work" }],
"meta":{
  "lastModified":"2015-04-15T12:46:18.224-06:00",
  "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{
  "display":"Users",  
  "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}

 

Patch Operation

The PATCH operation can be used to simplify changes to large multi-valued attributes, such as the membership of a group resource. To add a new member to a group resource you need to know the "id" of the resource you want to add and the type of resource it is (User or Group). The request to add a user (Meredith) to the "Software Developers" group using the PATCH operation is as follows:

curl -v -X PATCH --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "members" : [{ "value" : "a7d67610-ceb5-4350-ba5a-746472c4f1f7", "type" : "User" }] }' \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084

To remove a member from the group, include an "operation" attribute with the value of "delete", for example to remove Meredith from the "Software Developers" group:

curl -v -X PATCH --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "members" : [{ "value" : "a7d67610-ceb5-4350-ba5a-746472c4f1f7", , "type" : "User", "operation" : "delete" }] }' \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084

To delete a resource (user or group) you will use the DELETE operation against the resource’s endpoint. The following command will delete Meredith from the directory and return a 200 OK message if successful.

curl -v –X DELETE --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

As the SCIM protocol doesn’t define a method for authenticating a user. The PingOne Directory API uses the OAuth 2.0 Resource Owner Password Credential grant to facilitate user authentication.

To authenticate the Meredith user via her username/password, perform the following request:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-d "grant_type=password&username=marcher&password=2Federate" \
https://directory-api.pingone.com/api/directory/oauth/token

A response of 200 OK signals a successful login. Any other response is a failed authentication attempt.

This operation sets a confirmation token for the user associated with the specified email address. By default, a confirmation email is sent to that address. The confirmation email contains a link to reset their password. A new confirmation token is set for the user each time this operation is called.

The endpoint to reset a password by email:

https://directory-api.pingone.com/api/directory/users/password-lost

Request Parameters

Parameter DataType Description
email String The email address of the user.
link String Optional. The URL used to reset user passwords. If specified, this is included in the confirmation email. If not specified, the standard PingOne password reset form is used.
skip-send String Optional. This can be "enabled" (do not send an email) or "disabled" (send an email).

Request Example

This example sends an email with a link to a password-reset page:

{
  "email" : "jborder@anywhere.com",
  "link" : "https://anywhere.com/passwordReset"
  "skip-send" : "disabled"
}

If successful, the link is returned in the response, similar to the following:

HTTP/1.1 200 OK
{
"link": "https://login.pingone.com/idp/directory/a/61197468-2e9b-11e7-93ae-92361f008429/forgotpassword/confirm/611976e8-2e9b-11e7-93ae-92361f002671/611977f6-2e9b-11e7-93ae-92361f008429/"
}

This operation resets a user password based on the supplied user ID. You can specify either the oldPassword or the confirmationToken in the request, but not both. You can use the confirmationToken only to reset the password of non-administrative users.

The endpoint to reset a user's password:

https://directory-api.pingone.com/api/directory/users/password-reset

Request Parameters

Parameter DataType Description
id String The ID of the user.
newPassword String The new password to assign to the user.
oldPassword String Optional. The user's current password. You can specify this value or confirmationToken, but not both.
confirmationToken String Optional. The user's confirmation token. This cannot be used when you're resetting an administrator's password. You'll find the confirmation token on the user's account.

Request Example

This example resets the user's password by supplying the old password:

{
  "id" : "4ec0bb1e-37b0-414e-b27e-b17ec8ee9321",
  "newPassword" : "$ecret@123"
  "oldPassword" : "$ecret@456"
}

If successful, HTTP 200 OK is returned in the response.

 

To invite a new user to your directory you can supply an email address to the /useractions/invite endpoint. This will return the activation link the user will use to complete the registration. The activation link is valid for 24 hours.  

If the email invitation is sent to an existing user, this is a resend operation. The new activation link returned invalidates the previous activation link.

Here we invite Joe Border (jborder@pingdevelopers.com) to our directory instance:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "email" : "jborder@pingdevelopers.com" }' \
-X POST https://directory-api.pingone.com/api/directory/useractions/invite

The response is the invite activation URL contained in the email sent to the user: 

{"value":"https://login.pingone.com/idp/directory/a/1234-aaaa-bbbb-5678/registration/confirm/xxyy-jj88-abcd-12345678/abcd-9876-aaaa-87654321/"}

Joe will need to click on the activation button or link in the email to go to the registration page.

The email attribute is required, and will generate an email invitation using the default PingOne email invitation template. However, there are additional, optional attributes that you can specify to customize the email invitation for your organization. Here's an example:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data "@custom_email.json" \
-X POST https://directory-api.pingone.com/api/directory/useractions/invite

Where the content of custom_email.json looks like this:

{
"email": "jborder@pingdevelopers.com",
"alternateEmail": "jborder+home@pingdevelopers.com",
"fromName": "Custom Corp.",
"bodyText": "Custom email body",
"titleText": "Welcome to PingOne's customized invitation emails!",
"supportText": "Need support? Call ...",
"subject": "Activate your Custom Corp directory membership",
"activationButtonText": "This is a button!",
"link": "https://custom.com/register",
"footerText": "All your footers are belong to us.",
"footerLogoImage": "https://custom.com/images/customCorpFooter.png",
"headerImage": "http://custom.com/images/customCorpHeader.png",
"skipSend": "disabled",
"redirectLink": "https://mysite.custom.com"
}

Attribute descriptions

All of these attributes are optional. Any attributes that you don't specify use the default PingOne values.

alternateEmail: If specified, the invitation email is sent to this address instead of the primary email address.
fromName: The name of the email sender.
bodyText: The body of the email.
titleText: The title of the email (displayed above the body).
supportText: Contact information for further support.
subject: The email subject.
activationButtonText: The label used for the activation button.
link: The URL used for the activation button. This URL is also displayed below the button.
footerText: Text displayed in the footer of the email.
footerLogoImage: The URL for an image to be displayed in the email footer. Maximum size: 40 (width) x 70 (height).
headerImage: The URL for an image to be displayed in the email header. Maximum size: 606 (width) x 273 (height).
skipSend: When set to 'enabled', the email invitation isn't sent to the user, though the activation link is still returned in the response. If unspecified or set to any value other than 'enabled', the email is sent.
redirectLink: If specified, the user is redirected to the specified URL when they've completed their invitation process. By default, users are redirected to the PingOne dock. 

Preferences

You can use the /userregistration/preferences endpoint to customize the notifications sent that are related to user registrations. Conditions where notifications occur include, password expirations, forgotten passwords, invitations to register, and account locks. 

To get all of the current notification preferences for an account: 

curl -X GET "https://directory-api.pingone.com/api/directory/userregistration/preferences"

This response will be similar to the following (shown only for invite notification preferences, though preferences for all types will be returned):

{
  {"notification_name": "invite",
    "preferences": [
      {
        "values": [
         {
           "name": "product",
           "default_value": "PingOne ®"
         },
         {
           "name": "titleText",
           "default_value": "Welcome to PingOne ®"
         },
         {
           "name": "headerImage",
            "default_value": "http://someImages.com/email/images/activation.jpg"
         },
         {
           "name": "footerText",
           "default_value": ""
         },
         {
           "name": "activationButtonText",
           "default_value": "Activate PingOne ®"
         },
         {
           "name": "subject",
           "default_value": "You have been invited to use PingOne ®"
         },
         {
           "name": "supportText",
           "default_value": ""
         },
         {
           "name": "redirectLink",
           "default_value": "The URL to your PingOne"
         },
         {
           "name": "link",
           "default_value": "https://login.pingone.com/idp/directory/a/${accountId}/
                                registration/confirm/${userId}/${confirmationToken}/"
         },
         {
           "name": "footerLogoImage",
           "default_value": "http://someImages.com/email/images/general/logo.2x.png"
         },
         {
           "name": "bodyText",
           "default_value": " has invited you to PingOne ®.  You're just a few clicks away from
                              the security and convenience of single sign-on access to applications
                              you need to get your job done.  To get started, click the button below."
         },
         {
           "name": "fromName",
           "default_value": "PingOne"
         }
       ]
     }
   ]
 },
 .
 .
 .
]

You can also get the preferences for a single, specified type of notification (shown for forgotten passwords):

curl -X GET
  "https://test-directory-api.pingone.com/directory/userregistration/preferences/forgot_password"

This will return the preference settings used for forgotten password notifications, similar to the following:

{
 "notification_name": "forgot_password",
 "preferences": [
   {
     "values": [
       {
         "name": "product",
         "default_value": "PingOne ®"
       },
       {
         "name": "redirectLink",
         "default_value": "The URL to your PingOne"
       },
       {
         "name": "footerLogoImage",
         "default_value": "http://someImages.com/email/images/general/footer-logo.2x.png"
       },
       {
         "name": "fromName",
         "default_value": "PingOne"
       }
     ]
   }
 ]
}

You can also set or replace existing or default preference values, or remove preferences (only non-required fields). When notifications are sent, if you've not not assigned a notification preference, the default_value setting is used. 

A replace operation with a null value is the same as executing a remove operation.

You can set required fields to null (which will then use the default values). However, you can't set a required field to an empty string.

Required fields

For all email types:

  • fromName
  • product
  • subject

Additional fields

For all email types:

  • bannerText
  • titleText
  • bodyText
  • footerText
  • footerLogoImage

For all email types except self_registered_welcome:

  • activationButtonText
  • link

For invite and forgot_password only:

  • redirectLink

For invite only:

  • headerImage
  • supportText

The following example uses a replace operation:

curl -X PATCH --header "Content-Type: application/json" -d "{
 \"operations\": [
   {\"op\": \"replace\",
    \"path\": \"/forgot_password/preferences/product\",
    \"value\": \"myProduct\"
   }]
}" "https://test-directory-api.pingone.com/directory/userregistration/preferences"

The operation returns all notification preferences for the account. In the forgot_password notification type you'll find the changed product name.

 

 

 

An example of querying for the number of direct user membership of a group is:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084/users/count

Which will return the number of users in a JSON object:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "users" : 1
}