• Developer guide
  • API reference

›Authentication

Getting started

  • Introduction to Imply Polaris
  • Quickstart
  • Execute a POC
  • Create a dashboard
  • Navigate the console
  • Key concepts

Tables and data

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

Ingestion sources

  • Ingestion sources overview
  • Supported data formats
  • Create a connection
  • Ingest from files
  • Ingest data from a table
  • Ingest from S3
  • Ingest from Kafka and MSK
  • Ingest from Kinesis
  • Ingest from Confluent Cloud
  • Kafka Connector for Imply Polaris
  • Push event data
  • Connect to Confluent Schema Registry

Analytics

  • Overview
  • Manage data cubes
  • Visualize data
  • Data cube dimensions
  • Data cube measures
  • Dashboards
  • 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
    • Manage users
    • Permissions reference
    • Manage user groups
    • Enable SSO
    • SSO settings reference
    • Map IdP groups

    Secure networking

    • Connect to AWS
    • Create AWS PrivateLink connection

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 Kafka and MSK
    • 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
  • Specify data schema
  • 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

Authenticate with API keys

You can use API keys to authenticate REST API requests to the Polaris API via HTTP basic authentication. When authenticating with an API key, you don't need to reference your account credentials. Instead, you pass the API key in the HTTP header of your authentication request.

This topic describes how to create, use, and manage API keys to authenticate to the Polaris API. If your application authenticates with OAuth, see Authenticate with OAuth instead.

For development purposes, you can store API keys in environment variables on your machine. Examples in this topic store the API key value in the variable named POLARIS_API_KEY.

Prerequisites

To create and manage API keys, you must have one of the following permissions:

  • AdministerApiKeys: Users with this permission can view, create, and manage all API keys for their organization. Members of the Organization Admin and Project Admin groups have the AdministerApiKeys permission assigned to their profiles by default.
  • ManageApiKeys: Users with this permission can view and create API keys for their organization as well as and manage the API keys that they created. Members of the Data Manager group have the ManageApiKeys permission assigned to their profiles by default.

For more information on permissions, see Permissions reference.

Authentication

You authenticate to the Polaris API by including the API key in the HTTP header of your request.

To pass the key value in a curl command, use the -u or --user curl command-line option. Add a colon after the API key to prevent curl from asking for a password. curl converts the key value into a Base64-encoded string and adds the appropriate header to the request.

--user ${POLARIS_API_KEY}:

For example, to upload a file by passing the API key through the --user command-line option:

curl --location --request POST 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/files' \
--user ${POLARIS_API_KEY}: \
--form 'file=@"kttm-2019-08-20.json.gz"'

Alternatively, you can authenticate by passing the API key in the Authorization request header directly:

--header "Authorization: Basic $POLARIS_API_KEY"

For example, to upload a file by passing the API key through the request header:

curl --location --request POST 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/files' \
--header "Authorization: Basic $POLARIS_API_KEY" \
--form 'file=@"kttm-2019-08-20.json.gz"'

Create API keys

An API key represents a unique case-sensitive string that authorizes the use of the Polaris API. API keys are scoped to the organization—they do not follow the lifecycle of the Polaris user account. Each organization can have up to 20 API keys.

The maximum combined size of the API key name and description values is 191 bytes. One character does not equal one byte because Polaris supports Unicode characters, which take a variable number of bytes.

The API key is only visible in its entirety when you first create it. Each future access only shows the API key in redacted form.

API key permissions

You grant an API key access to resources by attaching permissions to the key. The permissions available to the API key are limited to the permissions of the Polaris account that created the key.

You can add and update permissions at any time during the key's lifecycle.

Create keys using the UI

Follow these steps to create an API key in the Polaris UI:

  1. Click API keys from the left navigation menu.
  2. Click New API key. Polaris displays a New API key dialog with form fields specific to API keys.
  3. Provide the following information for the API key:
    • Name: The name of the key.
    • Description: The description of the key.
    • Permissions: The list of permissions for the API key. You can only assign the permissions that you have access to.
  4. Click Create API key.
  5. A confirmation dialog is displayed. Save your API key. This is the only time that Polaris displays your API key in its entirety.

Once you successfully create the API key, you can use it to authenticate your API requests.

Create keys using the API

The API Keys API enables you to create additional API keys programmatically.

If you don't already have an API key to authenticate to Polaris, create one in the UI first. Make sure that your API key has either the AdministerApiKeys or the ManageApiKeys permission.

To create an API key, send a POST request to the /v1/apikeys endpoint. The API Keys API is a global API for Polaris, so do not include the cloud provider or region in the URL endpoint. See the API Keys API documentation for a description of required parameters.

Sample request

The following example shows how to create a demo API key named New API key:

cURL
Python
curl --location --request POST 'https://ORGANIZATION_NAME.api.imply.io/v1/apikeys' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '{
"name":"New API key",
"description":"New demo key",
"permissions": [
"AdministerQueries",
"ManageApiKeys",
"ManageDashboards",
"AccessQueries",
"ManageDataCubes",
"AccessVisualization",
"ManageTables",
"ManageFiles",
"ManageIngestionJobs",
"ManageTables"
]
}'
import os
import requests
import json

url = "https://ORGANIZATION_NAME.api.imply.io/v1/apikeys"

apikey = os.getenv("POLARIS_API_KEY")

payload = json.dumps({
"name": "New API key",
"description": "New demo key",
"permissions": [
"AdministerQueries",
"ManageApiKeys",
"ManageDashboards",
"AccessQueries",
"ManageDataCubes",
"AccessVisualization",
"ManageTables",
"ManageFiles",
"ManageIngestionJobs",
"ManageTables"
]
})
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Sample response

The following example shows a successful response:

{
    "id": "730b0bd3-c770-4501-99f8-f3adff537051",
    "name": "New API key",
    "description": "New demo key",
    "apiKey": "pok_bjSYK5qo8Fdcxxxxxxxy0edyR6yxxxxxxxxHdpbs2uvt5Aj6hfQeJs440YeinSUZ16",
    "redactedApiKey": "pok_bjSYK...nSUZ16",
    "permissions": [
        "ManageFiles",
        "AccessQueries",
        "AdministerQueries",
        "ManageDashboards",
        "ManageApiKeys",
        "ManageDataCubes",
        "ManageIngestionJobs",
        "ManageTables",
        "AccessVisualization"
    ],
    "createdBy": {
        "username": "api-key-pok_4gakz...k9kioy",
        "userId": "ef78eff2-d5dc-4d50-b46e-8306092a752a"
    },
    "lastModifiedBy": {},
    "createdOn": "2022-09-20T21:58:07.524Z"
}

The response body contains the following important fields:

  • apiKey: The secret key that authorizes the use of the Polaris API. Make sure to save the value of the apiKey property. The only time Polaris displays the API key in its entirety is when it is first created. All future requests return the redactedApiKey property that contains the API key in redacted form.
  • id: The unique identifier for the API key. The ID is required to retrieve or modify a single API key.

If you get a HTTP 401 Unauthorized status code, confirm that the organization name is correct in the endpoint of your request.

List API keys

You can view all of your organization's API keys on the API keys page of the Polaris UI.

The following screenshot shows the API keys view:

Polaris API keys view

To list all API keys using the API, send a GET request to the /v1/apikeys endpoint.

To view information for a single API key, send a GET request to the /v1/apikeys/{ID} endpoint. Replace {ID} with the ID of your API key. If you get a HTTP 403 User not authorized status code, verify that you are the creator of the API key or that you have the AdministerApiKeys permission.

Sample request

The following example shows how to list all API keys for an organization:

cURL
Python
curl --location --request GET 'https://ORGANIZATION_NAME.api.imply.io/v1/apikeys' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw ''
import os
import requests

url = "https://ORGANIZATION_NAME.api.imply.io/v1/apikeys"

apikey = os.getenv("POLARIS_API_KEY")

payload = ""
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Sample response

The following example shows a successful response:

Click to view the response

{
    "items": [
        {
            "id": "e38f9639-c7b3-4dc3-b5dd-70c570ee998e",
            "name": "Test key",
            "description": "Polaris API key for documentation",
            "redactedApiKey": "pok_2xwad...5waDGJ",
            "permissions": [
                "AdministerBilling",
                "AdministerProjects",
                "AdministerQueries",
                "AdministerApiKeys",
                "ManageProjects",
                "ViewTables",
                "AdministerDataCubes",
                "AccessVisualization",
                "AccessScaling",
                "AdministerDashboards",
                "AccessDownloadData",
                "AccessDownloadLargeData"
            ],
            "createdBy": {
                "username": "user@imply.io",
                "userId": "f4139753-be18-4ef1-acc1-3b8c8ec029c5"
            },
            "lastModifiedBy": {},
            "createdOn": "2022-09-16T15:14:22.401Z"
        },
        {
            "id": "ef78eff2-d5dc-4d50-b46e-8306092a752a",
            "name": "Polaris demo key",
            "description": "Demo key",
            "redactedApiKey": "pok_4gakz...k9kIOy",
            "permissions": [
                "ManageFiles",
                "AdministerBilling",
                "ManageConnections",
                "AdministerProjects",
                "ManageTables",
                "AdministerScaling",
                "AccessQueries",
                "AccessQueryRawData",
                "ManageApiKeys",
                "AccessScaling"
            ],
            "createdBy": {
                "username": "user@imply.io",
                "userId": "f4139753-be18-4ef1-acc1-3b8c8ec029c5"
            },
            "lastModifiedBy": {},
            "createdOn": "2022-09-20T21:47:07.055Z"
        },
        {
            "id": "730b0bd3-c770-4501-99f8-f3adff537051",
            "name": "New API key",
            "description": "New demo key",
            "redactedApiKey": "pok_bjSYK...nSUZ16",
            "permissions": [
                "AccessQueries",
                "ManageDashboards",
                "ManageFiles",
                "ManageApiKeys",
                "ManageDataCubes",
                "ManageIngestionJobs",
                "AdministerQueries",
                "ManageTables",
                "AccessVisualization"
            ],
            "createdBy": {
                "username": "api-key-pok_4gakz...k9kioy",
                "userId": "ef78eff2-d5dc-4d50-b46e-8306092a752a"
            },
            "lastModifiedBy": {},
            "createdOn": "2022-09-20T21:58:07.524Z"
        },
        {
            "id": "58991409-c1c2-4798-850d-144919808ba3",
            "name": "Analytics",
            "description": "Description",
            "redactedApiKey": "pok_dxhKr...swxxBR",
            "permissions": [
                "AdministerBilling",
                "ManageProjects",
                "ViewTables",
                "AdministerProjects"
            ],
            "createdBy": {
                "username": "user@imply.io",
                "userId": "6be578a1-9b8b-4c43-ae8b-b0e4504619c9"
            },
            "lastModifiedBy": {
                "username": "user@imply.io",
                "userId": "f4139753-be18-4ef1-acc1-3b8c8ec029c5"
            },
            "createdOn": "2022-09-14T18:13:39.494Z",
            "lastModifiedOn": "2022-09-21T02:39:02.124Z"
        },
        {
            "id": "a52cacf6-3ddc-48e5-8675-2f6ec5e0e917",
            "name": "Push streaming",
            "description": "",
            "redactedApiKey": "pok_VIpGJ...BJJVyO",
            "permissions": [
                "ManageDashboards",
                "ManageFiles",
                "AdministerProjects",
                "AdministerQueries",
                "AdministerAlerts",
                "AdministerApiKeys",
                "AccessMetrics",
                "AccessVisualization",
                "AccessScaling",
                "ManageAlertsWebhooks",
                "AdministerBilling",
                "ManageConnections",
                "ManageReports",
                "ManageDataCubes",
                "AdministerClients",
                "AccessAlerts",
                "ManageTables"
            ],
            "createdBy": {
                "username": "user@imply.io",
                "userId": "d84ec32d-933d-43b2-9904-ff806b2bab70"
            },
            "lastModifiedBy": {
                "username": "user@imply.io",
                "userId": "d84ec32d-933d-43b2-9904-ff806b2bab70"
            },
            "createdOn": "2022-09-15T20:58:34.711Z",
            "lastModifiedOn": "2022-09-15T21:52:34.914Z"
        }
    ]
}

Update API keys

You can edit the name, description, and permissions of an API key.

To update an API key in the Polaris UI, navigate to the API keys page and click the menu icon for the API key to update. Select Edit.

To update an API key using the API, send a PUT request to the /v1/apikeys/{ID} endpoint. Replace {ID} with the ID of your API key.

After you update the permissions for an API key, it can take up to five minutes for the changes to apply.

Sample request

The following example shows how to update an API key:

cURL
Python
curl --location --request PUT 'https://ORGANIZATION_NAME.api.imply.io/v1/apikeys/730b0bd3-c770-4501-99f8-f3adff537051' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Visualization API key",
"description": "Visualization demo key",
"permissions": [
"ManageDashboards",
"ManageFiles",
"ManageApiKeys",
"ManageDataCubes",
"AccessVisualization"
]
}'
import os
import requests
import json

url = "https://ORGANIZATION_NAME.api.imply.io/v1/apikeys/730b0bd3-c770-4501-99f8-f3adff537051"

apikey = os.getenv("POLARIS_API_KEY")

payload = json.dumps({
"name": "Visualization API key",
"description": "Visualization demo key",
"redactedApiKey": "pok_bjSYK...nSUZ16",
"permissions": [
"ManageDashboards",
"ManageFiles",
"ManageApiKeys",
"ManageDataCubes",
"AccessVisualization"
]
})
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

Sample response

The following example shows a successful response:

{
    "id": "730b0bd3-c770-4501-99f8-f3adff537051",
    "name": "Visualization API key",
    "description": "Visualization demo key",
    "redactedApiKey": "pok_bjSYK...nSUZ16",
    "permissions": [
        "ManageFiles",
        "ManageDashboards",
        "ManageApiKeys",
        "ManageDataCubes",
        "AccessVisualization"
    ],
    "createdBy": {
        "username": "api-key-pok_4gakz...k9kioy",
        "userId": "ef78eff2-d5dc-4d50-b46e-8306092a752a"
    },
    "lastModifiedBy": {
        "username": "api-key-pok_4gakz...k9kioy",
        "userId": "ef78eff2-d5dc-4d50-b46e-8306092a752a"
    },
    "createdOn": "2022-09-20T21:58:07.524Z",
    "lastModifiedOn": "2022-09-21T03:21:52.29Z"
}

Delete API keys

API keys never expire and must be kept secret and secure. If a key becomes compromised, you should delete it immediately. When you delete an API key, Polaris permanently removes it from the system. Deleted API keys cannot be used to authenticate to the Polaris API.

To delete an API key in the Polaris UI, navigate to the API key page and click the menu icon for the key you want to delete. Select Delete.

To delete an API key using the API, send a DELETE request to the /v1/apikeys/{ID} endpoint. Replace {ID} with the ID of your API key.

After you delete an API key, it can take up to five minutes for it to stop working.

Sample request

The following example shows how to delete an API key:

cURL
Python
curl --location --request DELETE 'https://ORGANIZATION_NAME.api.imply.io/v1/apikeys/730b0bd3-c770-4501-99f8-f3adff537051' \
--user ${POLARIS_API_KEY}: \
--header 'Content-Type: application/json' \
import os
import requests

url = "https://ORGANIZATION_NAME.api.imply.io/v1/apikeys/730b0bd3-c770-4501-99f8-f3adff537051"

apikey = os.getenv("POLARIS_API_KEY")

payload = ""
headers = {
'Authorization': f'Basic {apikey}',
'Content-Type': 'application/json'
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

Learn more

See the following topics for information on using the Polaris API:

  • API reference
  • API overview
  • Authentication overview
← OverviewAuthenticate with OAuth →
  • Prerequisites
  • Authentication
  • Create API keys
    • API key permissions
    • Create keys using the UI
    • Create keys using the API
  • List API keys
    • Sample request
    • Sample response
  • Update API keys
    • Sample request
    • Sample response
  • Delete API keys
    • Sample request
  • Learn more
Key links
Try ImplyApache Druid siteImply GitHub
Get help
Stack OverflowSupportContact us
Learn more
BlogApache Druid docs
Copyright © 2023 Imply Data, Inc