Quick start: top 6 API tasks

After you have set up your Postman collection and environment and obtained credentials, you're ready to work on tasks for your organization.

The following five tasks step you through the most common API operations to help you achieve your goals quickly by using the Postman collection.

Scenario: Jane Doe is a temporary employee hired to help during tax season. She needs to be added to the identity store and added to a new Taxes-Temp group. Jane then needs privileges so she can securely access applications.

Create a group

Groups help to organize sets of users. For example, a group might contain customers, partners, or accountants. Give the group a name and description that describes their role or purpose.

In our scenario, the group contains temporary tax professionals, so give the name, Taxes-Temp.

In Postman Collections, open Groups and select POST Create Group. Select the Body tab on the right side of the page.

Create the group, adding a description and meaningful group name in the payload.

{
    "urn:ietf:params:scim:schemas:extension:ldap:2.0:Group": {
        "description": "Group for the temp tax professionals group"
    },
    "displayName": "Taxes-Temp",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:ldap:2.0:Group"
    ]
}

In the Collections tab, send the request. You should see a 201 Created status and the response will look like this:

{
    "urn:ietf:params:scim:schemas:extension:ldap:2.0:Group": {
        "description": "Group for the temp tax professionals group"
    },
    "displayName": "Taxes-Temp",
    "meta": {
        "created": "2021-03-24T18:04:46Z",
        "location": "http://g3-iscim-default-iscim-default:8080/v2/Groups/c51e0fce-e856-49fd-a68f-5a37e5cf22b8",
        "lastModified": "2021-03-24T18:04:46Z",
        "version": "W\/\"lUPSm6puC1EJoJBAhAgoqUx4vvQ=\"",
        "resourceType": "Group"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:ldap:2.0:Group"
    ],
    "id": "c51e0fce-e856-49fd-a68f-5a37e5cf22b8"
}

Set the id as the group_id variable. In the above example the group ID is c51e0fce-e856-49fd-a68f-5a37e5cf22b8.
Highlight the group ID number and use the context menu to set it as the group_id variable.

Create a user

Create a user in an identity store by entering a user identity manually, one at a time. You can bulk-add multiple users to an identity store by uploading a CSV file in the Identity Store UI.

In our scenario, Jane Doe needs to be added to the identity store.

In Postman Collections, open Users and select POST Create User. Select the Body tab on the right side of the page.

Create the user, adding a password and unique user name in the payload.

{
      "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User",
          "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User",
          "urn:ietf:params:scim:schemas:extension:ldap:2.0:User"
      ],
      "userName": "Jane Doe",
      "password": "test123",
      "emails": [
      {
          "display": "janedoe@acme.com",
          "primary": true,
          "type": "work",
          "value": "janedoe@acme.com"
      }
    ],
      "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User": {
          "status": "active"
      }
}

Send the request. You should see a 201 Created status and the response will look like this:

{
    "emails": [
        {
            "display": "janedoe@acme.com",
            "type": "work",
            "value": "janedoe@acme.com",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User": {
        "resources": [
            "d39678e6-5c19-4112-7777-79e97da078f6"
        ],
        "groups": [
            {
                "groupId": "default"
            }
        ],
        "lastPasswordChange": "1617115297733",
        "status": "staged"
    },
    "meta": {
        "created": "2021-03-30T14:41:39Z",
        "location": "http://g3-iscim-default-iscim-default:8080/v2/Users/debbdc09-2140-4b7b-883a-b080e746988b",
        "lastModified": "2021-03-30T14:41:39Z",
        "version": "W\/\"IUt0cQODV8LA9umIekRPHDDDnz0=\"",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User",
        "urn:ietf:params:scim:schemas:extension:ldap:2.0:User"
    ],
    "id": "cf4931e8-1241-4954-8d71-1e1d9198e81f",
    "userName": "Jane Doe"
}

Set the user ID as the user_id variable. In the above example the user ID is cf4931e8-1241-4954-8d71-1e1d9198e81f.
Highlight the user ID number and use the context menu to set it as the user_id variable.
When you first create a user, their identity status is set to staged. You must set it to active so the user can authenticate.

Activate Jane's identity status by sending a PATCH Set user to active request.

{
    "emails": [
        {
            "display": "janedoe@acme.com",
            "type": "work",
            "value": "janedoe@acme.com",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User": {
        "resources": [
            "d39678e6-5c19-4112-7777-79e97da078f6"
        ],
        "groups": [
            {
                "groupId": "default"
            }
        ],
        "lastPasswordChange": "1617115297733",
        "status": "active"
    },
    "meta": {
        "created": "2021-03-30T14:51:39Z",
        "location": "http://g3-iscim-default-iscim-default:8080/v2/Users/debbdc09-2140-4b7b-883a-b080e746988b",
        "lastModified": "2021-03-30T14:51:39Z",
        "version": "W\/\"IUt0cQODV8LA9umIekRPHDDDnz0=\"",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User",
        "urn:ietf:params:scim:schemas:extension:ldap:2.0:User"
    ],
    "id": "cf4931e8-1241-4954-8d71-1e1d9198e81f",
    "userName": "Jane Doe"
}

Add a user to a group

After you have created a group and one or more users, you can add a user as a member of the group. Users in the group then follow the properties set for the group.

You must specify the user_id for the user you are adding and the group_id for the group you are adding the user to. Remember that you set these variables in the previous steps, so they will automatically be filled in for you.

In our scenario, Jane needs to be added to the Taxes-Temp group. She and other tax professionals were hired for a set three-month period, with a group expiration of April 30, 2021. Jane and the other users in the group will have access to certain applications until April 30, 2021, and then the access rights will automatically end.

In Postman Collections, open Users and select PATCH Add User to Groups. Select the Body tab on the right side of the page.

Add Jane to the group you created in the first task above. Because you set the group_id variable in a previous step, you do not need to add it to the payload.

In the payload below, you could add a date and time after "expirationDate" and then Jane's access rights would expire on that date and time. Setting an expiration date and time is not required, but it is useful to know.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User:groups",
            "value": [
                {
                    "groupId": "{{group_id}}",
                    "expirationDate": "2021-06-01T16:00:00Z"
                }
            ]
        }
    ]
}

Send the request. You should see a 200 OK status and the response will look like this:

 },
    "meta": {
        "created": "2021-03-30T14:41:39Z",
        "location": "http://g3-iscim-default-iscim-default:8080/v2/Users/debbdc09-2140-4b7b-883a-b080e746988b",
        "lastModified": "2021-03-30T14:49:40Z",
        "version": "W\/\"FY4QyTmRAnuBV5O4TrW5WKK+9aQ=\"",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User",
        "urn:ietf:params:scim:schemas:extension:ldap:2.0:User"
    ],
    "id": "cf4931e8-1241-4954-8d71-1e1d9198e81f",
    "userName": "Jane Doe"
}

Give a user privileges

A privilege defines the actions users can do with an application. Grant access to a user by assigning a privilege to a user or group. See Identity Store definitions to learn more about privileges.

In our scenario, Jane needs privileges to her group, Taxes-Temp, which will enable her to securely access the tax software and other apps she needs to do her job.

In Postman Collections, open Users and select PATCH Add Privilege to User. Select the Body tab on the right side of the page. Notice in the request that you need to specify the privilege_id, which is the set of privileges that you will give Jane.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "urn:ietf:params:scim:schemas:extension:secureauth:2.0:User:privileges",
            "value": [{"value": "{{privilege_id}}"}]
        }
    ]
}

Retrieve the privileges in the identity store to find the right privileges for Jane.

Open Privileges, select GET Retrieve Privileges, and send the request. You should see a 200 OK status and the response will look like this:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 19,
    "Resources": [
        {
            "id": "50564a33-9a7b-4410-9d85-1aff708c9ef7",
            "description": "Admin privileges, allows all actions over brandings, groups, users, password policies, resources and preferences",
            "name": "Admin"
        },
        {
            "id": "6b44b9ca-8379-494c-84a5-87de9a3fa98f",
            "description": "Admin Read-Only privileges, allows list and get actions over all resources",
            "name": "Admin Read-Only"
        },
        {
            "id": "df02c212-448a-4970-a6c6-05af70befb69",
            "name": "DataStore",
            "description": "Can view administer only data stores"
        },
        {
            "description": "Can view most objects",
            "name": "default",
            "id": "default"
        },
        {
            "id": "bcbbaefb-28cd-4877-97cd-3ff76aa12058",
            "description": "Developer privileges, allows obtaining and generating api credentials",
            "name": "Developer"
        },
        {
            "description": "Group privileges, allows all actions over groups",
            "name": "Group",
            "id": "c1a1bc94-6044-46a4-948b-74b6eaf1caf1"
        },
        {
            "name": "Group Can manage Developers dynamic privilege",
            "description": "Group Can manage Developers dynamic privilege",
            "id": "9e37a869-5bd4-4756-a1d2-9f8ea88fd8d1"
        },
        {
            "name": "Group Developers dynamic privilege",
            "description": "Group Developers dynamic privilege",
            "id": "c9f1f5b8-5827-4c82-8b95-1fb097c6b4e1"
        },
        {
            "name": "Group Marketing dynamic privilege",
            "description": "Group Marketing dynamic privilege",
            "id": "1063b640-28d4-492b-ab18-cb4e40a822b7"
        },
        {
            "name": "Group Sales dynamic privilege",
            "description": "Group Sales dynamic privilege",
            "id": "36239477-7870-474f-a7f8-42967388e902"
        },
        {
            "name": "Group TestGroup1 dynamic privilege",
            "description": "Group TestGroup1 dynamic privilege",
            "id": "c4219041-b0eb-4ad5-b193-82da7144f8e1"
        },
        {
            "name": "Group Taxes-Temp dynamic privilege",
            "description": "Group Taxes-Temp dynamic privilege",
            "id": "4a667194-89e2-4348-ba6c-a095d7346c4a"
        },
        {
            "name": "Help Desk",
            "id": "7e3f1c46-db4d-4f2d-b2eb-221f15101a19",
            "description": "Help desk privileges, allows all actions over users"
        },
        {
            "id": "bcbbaefb-28fe-4877-97ba-2ff76aa12058",
            "description": "IDS privileges, allows all actions over ids",
            "name": "IDS"
        },
        {
            "description": "Owner privileges, allows all actions",
            "name": "Owner",
            "id": "7b5d89f0-9b16-4943-a005-adde4c968877"
        },
        {
            "id": "6c9827ca-4a21-44d9-ab72-e36c45af6bbc",
            "description": "Preference privileges, allows all actions over preferences and brandings",
            "name": "Preference"
        },
        {
            "id": "2f1905d1-03fb-43b3-b426-f29249cd93ff",
            "description": "Privileges privileges, allows all actions over privileges",
            "name": "Privilege"
        },
        {
            "description": "Resources privileges, allows all actions over groups",
            "name": "Resource",
            "id": "289b01c8-a6f0-4234-85a5-7999119a35c3"
        },
        {
            "description": "User privileges, allows all actions over users",
            "name": "User",
            "id": "2779ea27-4e8f-473f-b105-9de689daaa6f"
        }
    ]
}

Give Jane privileges for the group you added her to, Taxes-Temp.
Highlight the Taxes-Temp ID and use the context menu to set it as the privilege_id variable. In the example above, the Taxes-Temp ID is 4a667194-89e2-4348-ba6c-a095d7346c4a.
Back in Users, select PATCH Add Privilege to User, and select the Body tab on the right side of the page. Notice in the request that you need to specify the privilege_id, which you have set.

Send the request. You should see a 200 OK status and the response will look like this:

{
    "privileges": {
        "Statement": [
            {
                "Action": [
                    "Group:List",
                    "Group:Get",
                    "Group:Show",
                    "Group:Delete",
                    "Group:Modify",
                    "Group:ManagePrivileges"
                ],
                "Scope": [
                    "0e461bc3-feb1-46b3-aac4-319a741a32a7"
                ],
                "Effect": "Allow"
            },
            {
                "Action": [
                    "User:List",
                    "User:Modify"
                ],
                "Scope": [
                    "*"
                ],
                "Effect": "Allow"
            },
            {
                "Action": [
                    "Privilege:List",
                    "Privilege:Get",
                    "Privilege:ManageGroups"
                ],
                "Scope": [
                    "*"
                ],
                "Effect": "Allow"
            }
        ]
    },
    "meta": {
        "created": "2021-03-28T02:55:22Z",
        "location": "http://g3-iscim-default-iscim-default:8080/v2/Privileges/4a667194-89e2-4348-ba6c-a095d7346c4a",
        "lastModified": "2021-03-28T02:55:22Z",
        "version": "W\/\"Bj2s836ZA07tbKIYlPgalhXfbX0=\"",
        "resourceType": "Privilege"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Privilege"
    ],
    "name": "Group Taxes-Temp dynamic privilege",
    "description": "Group Taxes-Temp dynamic privilege",
    "id": "4a667194-89e2-4348-ba6c-a095d7346c4a"
}

Delete a user

You might need to delete a user from an identity store for many reasons, some of which include:

User was accidentally added to the wrong identity store
User was not hired after all
User must be purged from data stores for HR reasons

In our scenario, Jane needs to be removed because she was accidentally added to the wrong identity store. You've already added Jane to the identity store, so you have set Jane's user_id and the ids_id variables. If you needed to find the IDs, you could run a retrieve to see them.

In Postman Collections, open Users and select DEL Delete User.
Send the request.
You should see a 204 No Content status, which confirms that Jane was successfully deleted from the identity store.

Change a user status

Users in your identity store will need to have status changes completed for many reasons, such as:

User is going on a leave of absence and his status needs to change from Active to Suspended. (Recall that you changed Jane's status in "Create a user" in step 5.
User is leaving the company and status needs to change from Active to Deactivated. Further, the user has requested the right to be forgotten (RTBF) so that all PII is removed from her profile.
User has requested a password reset so her status changes from Active to Password Reset until the operation is completed.

See Identity Store definitions to learn more about user statuses.

In our scenario, Jane is now leaving Acme. She asks the admin to remove her PII info. The admin can run a RTBF function from the Identity Platform UI for Jane or the admin or a dev can run an RTBF request from Postman or their development environment.

In Postman Collections, open Users and select POST Request User RTBF. Select the Body tab on the right side of the page.
You already set the user_id in a previous step.
Send the request.

You should see a 200 OK status and the response will look like this:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
    ],
    "Operations": [
        {
            "location": "http://g3-iscim-default-iscim-default:8080/v2/Users/cf4931e8-1241-4954-8d71-1e1d9198e81f",
            "method": "PUT",
            "bulkId": "cf4931e8-1241-4954-8d71-1e1d9198e81f",
            "version": "W\/\"HQ+OzxpL6ECLh9K7tjHmOgKlVVk=\"",
            "status": {
                "code": "200"
            }
        },
        {
            "location": "http://g3-iscim-default-iscim-default:8080/v2/Users/cf4931e8-1241-4954-8d71-1e1d9198e81f",
            "method": "PATCH",
            "bulkId": "cf4931e8-1241-4954-8d71-1e1d9198e81f",
            "version": "W\/\"09030W7Ax2uRcvSowkn8wsu0zQE=\"",
            "status": {
                "code": "200"
            }
        }
    ]
}

In this section: