• Developer guide
  • API reference

›Developer guide

Getting started

  • Introduction to Imply Polaris
  • Quickstart
  • Navigate the console
  • Key concepts

Ingestion sources

  • Ingestion sources overview
  • Supported data formats
  • Create a connection
  • Ingest from files
  • Ingest from S3
  • Ingest from Kinesis
  • Ingest from Confluent Cloud
  • Kafka Connector for Imply Polaris
  • Push event data

Tables and data

  • Overview
  • Introduction to tables
  • Table schema
  • Create an ingestion job
  • Timestamp expressions
  • Data partitioning
  • Introduction to rollup
  • Approximation algorithms
  • Replace data

Analytics

  • Overview
  • Manage data cubes
  • Visualize data
  • Data cube dimensions
  • Data cube measures
  • Dashboards
  • Create a dashboard
  • Visualizations reference
  • Set up alerts
  • Set up reports
  • Embed visualizations
  • Query data

Monitoring

  • Overview

Management

  • Overview
  • Pause and resume a project

Billing

  • Overview
  • Polaris plans
  • Estimate project costs

Usage

  • Overview

Security

    Polaris access

    • Overview
    • Invite users to your organization
    • Permissions reference
    • Manage user groups
    • Enable SSO
    • SSO settings reference
    • Map IdP groups

    Secure networking

    • Connect to AWS

Developer guide

  • Overview
  • Authentication

    • Overview
    • Authenticate with API keys
    • Authenticate with OAuth
  • Manage users and groups
  • Migrate deprecated resources
  • Create a table
  • Define a schema
  • Upload files
  • Create an ingestion job
  • Ingestion sources

    • Ingest from files
    • Ingest from a table
    • Get ARN for AWS access
    • Ingest from Amazon S3
    • Ingest from Amazon Kinesis
    • Ingest from Confluent Cloud
    • Push event data
    • Kafka Connector for Imply Polaris
    • Kafka Connector reference
  • Filter data to ingest
  • Ingest nested data
  • Ingest and query sketches
  • Query data
  • Update a project
  • Link to BI tools
  • Connect over JDBC
  • Query parameters reference
  • API documentation

    • OpenAPI reference
    • Query API

Product info

  • Release notes
  • Known limitations
  • Druid extensions

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
Python
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
Python
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
Python
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
Python
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
Python
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
Python
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
Python
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.
← Authenticate with OAuthMigrate deprecated resources →
  • Prerequisites
  • List all permissions
    • Sample request
    • Sample response
  • List all groups
    • Sample request
    • Sample response
  • Create a group
    • Sample request
    • Sample response
  • Create a user with group membership
    • Sample request
    • Sample response
  • Update a user
    • Sample request
    • Sample response
  • Add users to a group
    • Sample request
    • Sample response
  • List all group members
    • Sample request
    • Sample response
  • Learn more
Key links
Try ImplyApache Druid siteImply GitHub
Get help
Stack OverflowSupportContact us
Learn more
BlogApache Druid docs
Copyright © 2023 Imply Data, Inc