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:

Click API keys from the left navigation menu.
Click New API key. Polaris displays a New API key dialog with form fields specific to API keys.
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.
Click Create API key.
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:

Polaris access

Secure networking

Authentication

Ingestion sources

API documentation

Authenticate with API keys

Prerequisites

Authentication

Create API keys

API key permissions

Create keys using the UI

Create keys using the API

Sample request

Sample response

List API keys

Sample request

Sample response

Update API keys

Sample request

Sample response

Delete API keys

Sample request

Learn more