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 authenticate to the Polaris API with API keys. 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 the organization. Members of the Organization Admin group have the AdministerApiKeys permission assigned to their profiles by default.
• ManageApiKeys: Users with this permission can view and create API keys for the organization. Users can manage only the API keys that they create. 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}:

The following example shows how 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/projects/PROJECT_ID/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"

The following example shows how 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/projects/PROJECT_ID/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 associated with the organization and not individual users. If the user who generated an API key leaves the organization, the API key continues to be active until expired or revoked.

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 enable an API key to perform specific actions by applying permissions to the key. You can update permissions at any time during the key's lifecycle. The permissions available to the API key are limited to the permissions of the Polaris account that created the key.

API key permissions are scoped to the entire organization, that is they apply to all existing and future projects.

Create keys using the UI

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

1. Click the user menu icon located in the top-right corner of the page.
2. Select Administration from the user menu.
3. Click API keys from the left sidebar.
4. Click New API key. Polaris displays a New API key dialog with form fields specific to API keys.
5. 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.
6. Click Create API key.
7. 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

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"
    ]
}'

Python

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-xxxxxxxxxxxx"
    },
    "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:

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

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

Python

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-xxxxxxxxxxxx"
            },
            "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-xxxxxxxxxxxx"
            },
            "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-xxxxxxxxxxxx"
            },
            "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-xxxxxxxxxxxx"
            },
            "lastModifiedBy": {
                "username": "user@imply.io",
                "userId": "f4139753-be18-4ef1-acc1-xxxxxxxxxxxx"
            },
            "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-xxxxxxxxxxxx"
            },
            "lastModifiedBy": {
                "username": "user@imply.io",
                "userId": "d84ec32d-933d-43b2-9904-xxxxxxxxxxxx"
            },
            "createdOn": "2022-09-15T20:58:34.711Z",
            "lastModifiedOn": "2022-09-15T21:52:34.914Z"
        }
    ]
}

Update API keys

To update an API key in the Polaris UI, navigate to the API keys page and click the API key you want to update. This displays the API key details dialog, where you can edit the name, description, and permissions of the API key.

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

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"
    ]
}'

Python

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-xxxxxxxxxxxx"
    },
    "lastModifiedBy": {
        "username": "api-key-pok_4gakz...k9kioy",
        "userId": "ef78eff2-d5dc-4d50-b46e-xxxxxxxxxxxx"
    },
    "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

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" \

Python

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