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 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 its 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 thegroup_id
variable. In the above example the group ID isc51e0fce-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 iscf4931e8-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 toactive
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 theprivilege_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 a200 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 theprivilege_id
variable. In the example above, theTaxes-Temp
ID is4a667194-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 theprivilege_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" } } ] }