Manage users and groups through API
Imply Polaris provides an API for managing users and groups.
The Identity management API enables you to perform the following tasks:
- List all the permissions for an organization
- Create, update, and delete users
- Create, update, and delete groups
- Retrieve information for a specific user or a group
The Identity management API supports multiple ways of adding users to a group:
- Add a new user to one or more groups at user creation time using the Create a user method.
- Add an existing user to one or more groups using the Update a user method.
- Add one or more users to a single group using the Add users to a group method.
This topic shows you how to create and manage users through the Identity management API. It also explains how to create a group and add a user to that group. For information on managing users and groups in the UI, see Add users to an organization and Manage user groups respectively.
Prerequisites
Before you begin, familiarize yourself with the concepts of permissions and groups.
To follow along with this tutorial, you need an API key with the AdministerUsers permission.
In the examples below, Polaris reads the key value from an environment variable named POLARIS_API_KEY.
See Authenticate with API keys to obtain an API key and assign permissions.
When running the code in the examples, replace ORGANIZATION_NAME with the custom domain through which you access Polaris. For example, https://ORGANIZATION_NAME.app.imply.io.
List all permissions
Permissions determine the operations a user can perform. You grant permissions to users through groups. Specifically, you assign permissions to a group and then add users as members of the group. For more information on permissions, see Permissions reference.
To retrieve a list of all permissions, send a GET request to the /v1/permissions endpoint.
Sample request
The following request retrieves a list of all permissions:
curl --location --request GET 'https://ORGANIZATION_NAME.app.imply.io/v1/permissions' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
import os
import requests
url = "https://ORGANIZATION_NAME.app.imply.io/v1/permissions"
apikey = os.getenv("POLARIS_API_KEY")
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.json())
Sample response
A successful request returns a 200 OK response and the list of permissions.
Click to view the response
{
"values": [
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "911fc520-3b01-4c8b-959f-20ab2b17374a",
"name": "AdministerEmbedLinks",
"description": "Imported by role importer"
},
{
"id": "6345470f-131e-471f-b814-6f908566eea1",
"name": "ReadDataSources"
},
{
"id": "0cc4d1d4-ec9c-4270-a37f-9ff518ef14ea",
"name": "ManageFiles"
},
{
"id": "092a5652-f964-48e6-ba12-2296180bc54d",
"name": "AdministerProjects"
},
{
"id": "ab5a1746-594f-45f4-b116-451799e58cf6",
"name": "AdministerAlerts"
},
{
"id": "78b4d71d-6c67-471c-b308-06f359a711a7",
"name": "AdministerQueries"
},
{
"id": "1beed243-665d-434b-ba5c-38dd7ed0e6ff",
"name": "AdministerApiKeys"
},
{
"id": "69163829-a7a0-4685-b098-6c493b374b3a",
"name": "AccessMetrics"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization",
"description": "Imported by role importer"
},
{
"id": "2b2e9fd9-38a7-4344-ac5a-828710a1b7dd",
"name": "AccessScaling"
},
{
"id": "f6d591a6-ac5f-480d-96df-0479cb1d96f5",
"name": "AdministerBilling",
"description": "Allows clients to see and update payment info"
},
{
"id": "9f38f3ae-949b-4985-8b22-7f0321ead5ad",
"name": "ManageAlertsWebhooks"
},
{
"id": "6bb36198-c3e2-478d-92fe-2b0d34429140",
"name": "ManageConnections"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "94282ff7-c81a-4ade-8e7b-3f73b9928d2f",
"name": "ManageReports"
},
{
"id": "2cdd7c9b-8717-498a-93e0-907f978763fd",
"name": "AccessAlerts"
},
{
"id": "1331c332-8978-45b8-a028-ac98072d50d6",
"name": "AdministerClients"
},
{
"id": "e4731eed-8a1b-411b-8684-c812dc808fd3",
"name": "ManageTables"
},
{
"id": "3d28aad6-2048-4376-be63-cbf8897ea79b",
"name": "AccessReports",
"description": "Imported by role importer"
},
{
"id": "4c8be600-e36f-49c3-8c9e-e895158f0b3d",
"name": "AdministerScaling"
},
{
"id": "3a34eebd-c555-4ad8-a0bc-435377989c1d",
"name": "AccessQueries"
},
{
"id": "37964e4e-40c2-4615-8c96-34d894c0b117",
"name": "AccessQueryRawData"
},
{
"id": "ea143f33-cde0-4307-bc2c-8a090c0d2ea5",
"name": "AccessMonitorQueries"
},
{
"id": "b13afd48-3bcf-4625-ad0d-4a6efb228f26",
"name": "ManageApiKeys",
"description": "Imported by role importer"
},
{
"id": "ea35493e-3605-482d-b991-b1d3d6815bfa",
"name": "AdministerDataCubes"
},
{
"id": "407c27b1-b858-474b-9506-4853d9917894",
"name": "ManageProjects"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "e44a20bb-214b-4e94-b073-4ec48a5c8c2a",
"name": "ManageIngestionJobs"
},
{
"id": "57ae83c4-23a9-4a96-918b-43c59ea4e013",
"name": "AdministerUsers"
},
{
"id": "500c9605-64bd-4a8d-9f1e-586bdf30aada",
"name": "AdministerReports"
},
{
"id": "f7da9a27-3645-4a08-a32a-7fdefaaa3a19",
"name": "AccessDownloadData"
},
{
"id": "79138630-726a-4f9a-ac49-4ffe1d5f970d",
"name": "AdministerDashboards"
},
{
"id": "a3122c6b-1ab9-48a7-a4a7-2333d62ea90e",
"name": "AccessDownloadLargeData"
},
{
"id": "b33f4969-9c9d-4191-838a-65815c1b64f8",
"name": "ManageAlerts"
}
]
}
List all groups
To grant permissions to a user, first identify the group that has the necessary permissions, then assign that group to the user.
Polaris provides predefined groups that correspond to specific organizational roles. You can also create your own groups with finer-grained access control. Before you create a new group, it is a good practice to verify that a similar group does not already exist for your organization.
To retrieve a list of all groups, send a GET request to the /v1/groups endpoint.
Sample request
The following request retrieves a list of all groups:
curl --location --request GET 'https://ORGANIZATION_NAME.app.imply.io/v1/groups' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
import os
import requests
url = "https://ORGANIZATION_NAME.app.imply.io/v1/groups"
apikey = os.getenv("POLARIS_API_KEY")
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.json())
Sample response
A successful request returns a 200 OK response and the list of groups.
Click to view the response
{
"values": [
{
"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d",
"name": "Data Analyst",
"readOnly": true,
"permissions": [
{
"id": "3a34eebd-c555-4ad8-a0bc-435377989c1d",
"name": "AccessQueries"
},
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "2cdd7c9b-8717-498a-93e0-907f978763fd",
"name": "AccessAlerts"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
},
{
"id": "2b2e9fd9-38a7-4344-ac5a-828710a1b7dd",
"name": "AccessScaling"
},
{
"id": "3d28aad6-2048-4376-be63-cbf8897ea79b",
"name": "AccessReports"
},
{
"id": "f7da9a27-3645-4a08-a32a-7fdefaaa3a19",
"name": "AccessDownloadData"
},
{
"id": "a3122c6b-1ab9-48a7-a4a7-2333d62ea90e",
"name": "AccessDownloadLargeData"
}
],
"userCount": 4
},
{
"id": "6b7612cf-7687-4d6e-a036-665655f20550",
"name": "Data Manager",
"readOnly": true,
"permissions": [
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "0cc4d1d4-ec9c-4270-a37f-9ff518ef14ea",
"name": "ManageFiles"
},
{
"id": "9f38f3ae-949b-4985-8b22-7f0321ead5ad",
"name": "ManageAlertsWebhooks"
},
{
"id": "6bb36198-c3e2-478d-92fe-2b0d34429140",
"name": "ManageConnections"
},
{
"id": "94282ff7-c81a-4ade-8e7b-3f73b9928d2f",
"name": "ManageReports"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "78b4d71d-6c67-471c-b308-06f359a711a7",
"name": "AdministerQueries"
},
{
"id": "2cdd7c9b-8717-498a-93e0-907f978763fd",
"name": "AccessAlerts"
},
{
"id": "e4731eed-8a1b-411b-8684-c812dc808fd3",
"name": "ManageTables"
},
{
"id": "69163829-a7a0-4685-b098-6c493b374b3a",
"name": "AccessMetrics"
},
{
"id": "3d28aad6-2048-4376-be63-cbf8897ea79b",
"name": "AccessReports"
},
{
"id": "4c8be600-e36f-49c3-8c9e-e895158f0b3d",
"name": "AdministerScaling"
},
{
"id": "3a34eebd-c555-4ad8-a0bc-435377989c1d",
"name": "AccessQueries"
},
{
"id": "37964e4e-40c2-4615-8c96-34d894c0b117",
"name": "AccessQueryRawData"
},
{
"id": "ea143f33-cde0-4307-bc2c-8a090c0d2ea5",
"name": "AccessMonitorQueries"
},
{
"id": "b13afd48-3bcf-4625-ad0d-4a6efb228f26",
"name": "ManageApiKeys"
},
{
"id": "407c27b1-b858-474b-9506-4853d9917894",
"name": "ManageProjects"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "e44a20bb-214b-4e94-b073-4ec48a5c8c2a",
"name": "ManageIngestionJobs"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
},
{
"id": "2b2e9fd9-38a7-4344-ac5a-828710a1b7dd",
"name": "AccessScaling"
},
{
"id": "f7da9a27-3645-4a08-a32a-7fdefaaa3a19",
"name": "AccessDownloadData"
},
{
"id": "a3122c6b-1ab9-48a7-a4a7-2333d62ea90e",
"name": "AccessDownloadLargeData"
},
{
"id": "b33f4969-9c9d-4191-838a-65815c1b64f8",
"name": "ManageAlerts"
}
],
"userCount": 118
},
{
"id": "540cbe7b-c283-4824-804e-566a3d22f3ac",
"name": "Organization Admin",
"readOnly": true,
"permissions": [
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "0cc4d1d4-ec9c-4270-a37f-9ff518ef14ea",
"name": "ManageFiles"
},
{
"id": "092a5652-f964-48e6-ba12-2296180bc54d",
"name": "AdministerProjects"
},
{
"id": "78b4d71d-6c67-471c-b308-06f359a711a7",
"name": "AdministerQueries"
},
{
"id": "ab5a1746-594f-45f4-b116-451799e58cf6",
"name": "AdministerAlerts"
},
{
"id": "1beed243-665d-434b-ba5c-38dd7ed0e6ff",
"name": "AdministerApiKeys"
},
{
"id": "69163829-a7a0-4685-b098-6c493b374b3a",
"name": "AccessMetrics"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
},
{
"id": "2b2e9fd9-38a7-4344-ac5a-828710a1b7dd",
"name": "AccessScaling"
},
{
"id": "9f38f3ae-949b-4985-8b22-7f0321ead5ad",
"name": "ManageAlertsWebhooks"
},
{
"id": "f6d591a6-ac5f-480d-96df-0479cb1d96f5",
"name": "AdministerBilling"
},
{
"id": "6bb36198-c3e2-478d-92fe-2b0d34429140",
"name": "ManageConnections"
},
{
"id": "94282ff7-c81a-4ade-8e7b-3f73b9928d2f",
"name": "ManageReports"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "1331c332-8978-45b8-a028-ac98072d50d6",
"name": "AdministerClients"
},
{
"id": "2cdd7c9b-8717-498a-93e0-907f978763fd",
"name": "AccessAlerts"
},
{
"id": "e4731eed-8a1b-411b-8684-c812dc808fd3",
"name": "ManageTables"
},
{
"id": "3d28aad6-2048-4376-be63-cbf8897ea79b",
"name": "AccessReports"
},
{
"id": "4c8be600-e36f-49c3-8c9e-e895158f0b3d",
"name": "AdministerScaling"
},
{
"id": "3a34eebd-c555-4ad8-a0bc-435377989c1d",
"name": "AccessQueries"
},
{
"id": "37964e4e-40c2-4615-8c96-34d894c0b117",
"name": "AccessQueryRawData"
},
{
"id": "ea143f33-cde0-4307-bc2c-8a090c0d2ea5",
"name": "AccessMonitorQueries"
},
{
"id": "407c27b1-b858-474b-9506-4853d9917894",
"name": "ManageProjects"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "ea35493e-3605-482d-b991-b1d3d6815bfa",
"name": "AdministerDataCubes"
},
{
"id": "e44a20bb-214b-4e94-b073-4ec48a5c8c2a",
"name": "ManageIngestionJobs"
},
{
"id": "57ae83c4-23a9-4a96-918b-43c59ea4e013",
"name": "AdministerUsers"
},
{
"id": "500c9605-64bd-4a8d-9f1e-586bdf30aada",
"name": "AdministerReports"
},
{
"id": "79138630-726a-4f9a-ac49-4ffe1d5f970d",
"name": "AdministerDashboards"
},
{
"id": "f7da9a27-3645-4a08-a32a-7fdefaaa3a19",
"name": "AccessDownloadData"
},
{
"id": "a3122c6b-1ab9-48a7-a4a7-2333d62ea90e",
"name": "AccessDownloadLargeData"
},
{
"id": "b33f4969-9c9d-4191-838a-65815c1b64f8",
"name": "ManageAlerts"
}
],
"userCount": 33
},
{
"id": "663c5e80-2cc9-4dc8-8895-afbecaf4a29a",
"name": "Project Admin",
"readOnly": true,
"permissions": [
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "0cc4d1d4-ec9c-4270-a37f-9ff518ef14ea",
"name": "ManageFiles"
},
{
"id": "78b4d71d-6c67-471c-b308-06f359a711a7",
"name": "AdministerQueries"
},
{
"id": "ab5a1746-594f-45f4-b116-451799e58cf6",
"name": "AdministerAlerts"
},
{
"id": "1beed243-665d-434b-ba5c-38dd7ed0e6ff",
"name": "AdministerApiKeys"
},
{
"id": "69163829-a7a0-4685-b098-6c493b374b3a",
"name": "AccessMetrics"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
},
{
"id": "2b2e9fd9-38a7-4344-ac5a-828710a1b7dd",
"name": "AccessScaling"
},
{
"id": "9f38f3ae-949b-4985-8b22-7f0321ead5ad",
"name": "ManageAlertsWebhooks"
},
{
"id": "6bb36198-c3e2-478d-92fe-2b0d34429140",
"name": "ManageConnections"
},
{
"id": "94282ff7-c81a-4ade-8e7b-3f73b9928d2f",
"name": "ManageReports"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "2cdd7c9b-8717-498a-93e0-907f978763fd",
"name": "AccessAlerts"
},
{
"id": "e4731eed-8a1b-411b-8684-c812dc808fd3",
"name": "ManageTables"
},
{
"id": "3d28aad6-2048-4376-be63-cbf8897ea79b",
"name": "AccessReports"
},
{
"id": "4c8be600-e36f-49c3-8c9e-e895158f0b3d",
"name": "AdministerScaling"
},
{
"id": "3a34eebd-c555-4ad8-a0bc-435377989c1d",
"name": "AccessQueries"
},
{
"id": "37964e4e-40c2-4615-8c96-34d894c0b117",
"name": "AccessQueryRawData"
},
{
"id": "ea143f33-cde0-4307-bc2c-8a090c0d2ea5",
"name": "AccessMonitorQueries"
},
{
"id": "407c27b1-b858-474b-9506-4853d9917894",
"name": "ManageProjects"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "ea35493e-3605-482d-b991-b1d3d6815bfa",
"name": "AdministerDataCubes"
},
{
"id": "e44a20bb-214b-4e94-b073-4ec48a5c8c2a",
"name": "ManageIngestionJobs"
},
{
"id": "500c9605-64bd-4a8d-9f1e-586bdf30aada",
"name": "AdministerReports"
},
{
"id": "79138630-726a-4f9a-ac49-4ffe1d5f970d",
"name": "AdministerDashboards"
},
{
"id": "f7da9a27-3645-4a08-a32a-7fdefaaa3a19",
"name": "AccessDownloadData"
},
{
"id": "a3122c6b-1ab9-48a7-a4a7-2333d62ea90e",
"name": "AccessDownloadLargeData"
},
{
"id": "b33f4969-9c9d-4191-838a-65815c1b64f8",
"name": "ManageAlerts"
}
],
"userCount": 7
},
{
"id": "d919f276-7857-4b59-a616-0c2540fb4ad1",
"name": "Viewer",
"readOnly": true,
"permissions": [
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
}
],
"userCount": 16
}
]
}
Create a group
If none of the predefined groups satisfy your requirements, you can create a custom group with a specific set of permissions.
To create a group, send a POST request to the /v1/groups endpoint.
For a description of required parameters, see the Create a group documentation.
Sample request
The following request creates a custom group named Data visualization specialist:
curl --location --request POST 'https://ORGANIZATION_NAME.app.imply.io/v1/groups' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Data visualization specialist",
"permissions": [
{
"name": "ViewTables"
},
{
"name": "AccessVisualization"
},
{
"name": "ManageDataCubes"
},
{
"name": "ManageDashboards"
}
]
}'
import os
import requests
import json
url = "https://ORGANIZATION_NAME.app.imply.io/v1/groups"
apikey = os.getenv("POLARIS_API_KEY")
payload = json.dumps({
"name": "Data visualization specialist",
"permissions": [
{
"name": "ViewTables"
},
{
"name": "AccessVisualization"
},
{
"name": "ManageDataCubes"
},
{
"name": "ManageDashboards"
}
]
})
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())
Sample response
A successful request returns a 201 Created response and the details of the group:
{
"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af",
"name": "Data visualization specialist",
"readOnly": false,
"permissions": [
{
"id": "7f9d4778-b6f5-4d07-9eb8-66f6fa8490a6",
"name": "ManageDashboards"
},
{
"id": "d5fae740-1d05-4c85-88d2-a3344b65e563",
"name": "ViewTables"
},
{
"id": "d66d32f9-b01a-47bc-ae13-b598575e2302",
"name": "ManageDataCubes"
},
{
"id": "f078bb59-857c-4abd-9c12-16568ea66510",
"name": "AccessVisualization"
}
],
"userCount": 0
}
Create a user with group membership
To add a user to a group when the user is first created, send a POST request to the /v1/users endpoint. Pass a list of group IDs to the groups property in the user object.
For a description of required parameters, see the Create a user documentation.
Sample request
The following example demonstrates how to create a new user and assign that user to the Data visualization specialist group.
Note that the groups property contains the group ID that corresponds to the Data visualization specialist group.
When you assign users to groups, use the group ID instead of the group name.
curl --location --request POST 'https://ORGANIZATION_NAME.app.imply.io/v1/users' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "alex.smith@example.com",
"firstName": "Alex",
"lastName": "Smith",
"groups": [
{"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af"}
]
}'
import os
import requests
import json
url = "https://ORGANIZATION_NAME.app.imply.io/v1/users"
apikey = os.getenv("POLARIS_API_KEY")
payload = json.dumps({
"username": "alex.smith@example.com",
"firstName": "Alex",
"lastName": "Smith",
"groups": [
{
"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af"
}
]
})
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())
Sample response
A successful request returns a 201 Created response and the details of the user:
{
"id": "48b08425-7393-4730-bb7d-736e69ef1d92",
"username": "alex.smith@example.com",
"email": "alex.smith@example.com",
"firstName": "Alex",
"lastName": "Smith",
"enabled": true,
"emailVerified": false,
"permissions": [],
"groups": [
{
"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af",
"name": "Data visualization specialist",
"permissions": []
}
],
"identities": [],
"actions": [
"VERIFY_EMAIL",
"UPDATE_PASSWORD"
],
"createdOn": "2023-01-17T19:57:38.763Z"
}
Update a user
To update a user, send a PUT request to the /v1/users/{id} endpoint.
Replace the {id} path parameter with the ID of the user you want to update.
The PUT method is intended to replace the entire resource; thus, your request body must include the full set of attributes.
The username and email properties of the user object cannot be modified.
For more information, see the Update a user documentation.
Sample request
The following request adds a user, who is a member of the Data visualization specialist group, to the group named Data Analyst.
curl --location --request PUT 'https://ORGANIZATION_NAME.app.imply.io/v1/users/48b08425-7393-4730-bb7d-736e69ef1d92' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "alex.smith@example.com",
"email": "alex.smith@example.com",
"enabled": true,
"groups": [
{"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af"},
{"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d"}
]
}'
import os
import requests
import json
url = "https://ORGANIZATION_NAME.app.imply.io/v1/users/d88d4e47-d6ed-4820-880e-c0564ce99752"
apikey = os.getenv("POLARIS_API_KEY")
payload = json.dumps({
"username": "alex.smith@example.com",
"email": "alex.smith@example.com",
"enabled": True,
"groups": [
{"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af"},
{"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d"}
]
})
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.put(url, headers=headers, data=payload)
print(response.json())
Sample response
A successful request returns a 200 OK response and the details of the user:
{
"id": "48b08425-7393-4730-bb7d-736e69ef1d92",
"username": "alex.smith@example.com",
"email": "alex.smith@example.com",
"firstName": "Alex",
"lastName": "Smith",
"enabled": true,
"emailVerified": false,
"permissions": [],
"groups": [
{
"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d",
"name": "Data Analyst",
"permissions": []
},
{
"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af",
"name": "Data visualization specialist",
"permissions": []
}
],
"identities": [],
"actions": [
"UPDATE_PASSWORD",
"VERIFY_EMAIL"
],
"createdOn": "2023-01-17T19:57:38.763Z"
}
Add users to a group
To add one or more users to a group, send a POST request to the /v1/groups/{id}/members endpoint.
Replace the {id} path parameter with the ID of the group you want to add users to.
For more information, see the Add users to a group documentation.
Sample request
The following request adds two new users to the Data Analyst group, ID de7af765-6235-4b18-a5ab-2314e28c9e0d.
Note that the payload is an array of user objects.
curl --location --request POST 'https://ORGANIZATION_NAME.app.imply.io/v1/groups/de7af765-6235-4b18-a5ab-2314e28c9e0d/members' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '[
{"id": "48b08425-7393-4730-bb7d-736e69ef1d92"},
{"id": "83362895-7d26-42f5-b364-ec758691e983"}
]'
import os
import requests
import json
url = "https://ORGANIZATION_NAME.app.imply.io/v1/groups/de7af765-6235-4b18-a5ab-2314e28c9e0d/members"
apikey = os.getenv("POLARIS_API_KEY")
payload = json.dumps([
{"id": "d88d4e47-d6ed-4820-880e-c0564ce99752"},
{"id": "83362895-7d26-42f5-b364-ec758691e983"}
])
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)
Sample response
A successful request returns a 200 OK response.
List all group members
To retrieve a list of group members, send a GET request to the /v1/groups/{id}/members endpoint. Replace the {id} path parameter with the ID of the group.
Sample request
The following request returns a list of group members for group ID de7af765-6235-4b18-a5ab-2314e28c9e0d:
curl --location --request GET 'https://ORGANIZATION_NAME.app.imply.io/v1/groups/de7af765-6235-4b18-a5ab-2314e28c9e0d/members' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
import os
import requests
url = "https://ORGANIZATION_NAME.app.imply.io/v1/groups/de7af765-6235-4b18-a5ab-2314e28c9e0d/members"
apikey = os.getenv("POLARIS_API_KEY")
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.json())
Sample response
A successful request returns a 200 OK response and the list of group members.
Click to view the response
{
"values": [
{
"id": "48b08425-7393-4730-bb7d-736e69ef1d92",
"username": "alex.smith@example.com",
"email": "alex.smith@example.com",
"firstName": "Alex",
"lastName": "Smith",
"enabled": true,
"emailVerified": false,
"permissions": [],
"groups": [
{
"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d",
"name": "Data Analyst",
"permissions": []
},
{
"id": "fba60eae-5d5a-45e2-ac5a-86a49caeb6af",
"name": "Data visualization specialist",
"permissions": []
}
],
"identities": [],
"actions": [
"VERIFY_EMAIL",
"UPDATE_PASSWORD"
],
"createdOn": "2023-01-17T19:57:38.763Z"
},
{
"id": "83362895-7d26-42f5-b364-ec758691e983",
"username": "dani.lee@example.com",
"email": "dani.lee@example.com",
"firstName": "Dani",
"lastName": "Lee",
"enabled": true,
"emailVerified": false,
"permissions": [],
"groups": [
{
"id": "de7af765-6235-4b18-a5ab-2314e28c9e0d",
"name": "Data Analyst",
"permissions": []
}
],
"identities": [],
"actions": [
"VERIFY_EMAIL",
"UPDATE_PASSWORD"
],
"createdOn": "2023-01-13T17:05:52.506Z"
}
],
"count": 2
}
Learn more
See the following topics for more information:
- Identity management API for details on the Identity management API.
- Permissions reference for details on user permissions.
- Manage user groups for information on how to manage user groups in the Polaris UI.