Skip to main content

Authenticate with OAuth

You can use the OAuth 2.0 authorization framework to authenticate REST API requests to the Polaris API.

To authenticate your API request:

  1. Create a custom OAuth client to obtain OAuth 2.0 credentials such as a client ID and client secret from the Polaris console.

  2. Obtain an access token. The access token is tied to the OAuth client and grants API access.

  3. Send the access token to the Polaris API in the HTTP Authorization request header using the Bearer authentication scheme:

    Authorization: Bearer <ACCESS_TOKEN>
info

Projects created after September 29, 2023 require project-scoped access tokens for OAuth authentication to regional API resources. Existing OAuth clients will continue to work for projects created before September 29, 2023.

Create a custom OAuth client​

To create and manage OAuth clients, you must be a member of the Organization Admin group or have the AdministerClients permission assigned to your profile. For information on permissions, see Permissions reference. For instructions on how to add a user to a group, see Add users to a group.

Create a custom OAuth client as follows:

  1. In the Polaris UI, click the Administration gear icon located in the top-right corner of the page.
  2. Click OAuth clients in the left sidebar.
  3. Click Manage OAuth clients.
  4. On the OAuth Clients page, click Create.
  5. Enter a unique name for your OAuth client in the OAuth Client ID field.
  6. Click Save.

Access token lifespan​

info

The OAuth authentication method does not support long-lived tokens. We recommend using API keys to authenticate to the Polaris API because API keys never expire.

The lifespan of an access token is five minutes. Polaris automatically revokes access tokens when they reach their configured lifespan. Requests that contain expired access tokens return an HTTP 401 status code with the following body:

{
    "message": "Token claims invalid: [\"exp\"]=\"token expired\""
}

Assign permissions to an OAuth client​

You enable an OAuth client to perform specific actions by assigning permissions. Permissions assigned to an OAuth client can access all projects within an organization. If you need an authentication method that supports per project permissions, use API keys to authenticate to the Polaris API instead.

To assign permissions to an OAuth client:

  1. On the OAuth Clients page, click the ID of your OAuth client.
  2. Click the Client Permissions tab.
  3. Select the applicable permissions from the Available Permissions menu. To select multiple permissions, press and hold the Shift key while selecting permissions.
  4. Click Add selected.

Obtain access tokens​

To obtain an access token, send a POST request to the following endpoint: https://id.imply.io/auth/realms/ORGANIZATION_NAME/protocol/openid-connect/token

Include the client ID and client secret in the request. If you don't know your client secret, go to the Credentials tab in the UI to retrieve it. To scope your access token to a specific project, include the scope parameter using the "scope=project-PROJECT_ID" format.

For example:

curl --request POST "https://id.imply.io/auth/realms/ORGANIZATION_NAME/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "grant_type=client_credentials" \
--data "scope=project-PROJECT_ID" \

Replace the following:

  • ORGANIZATION_NAME: The custom domain through which you access Polaris.
  • CLIENT_ID: The name of the OAuth client you configured.
  • CLIENT_SECRET: The secret generated for the OAuth client.
  • PROJECT_ID: The unique identifier for your Polaris project.

Sample request​

The following example shows how to obtain an access token for the MPS-test OAuth client:

curl --request POST "https://id.imply.io/auth/realms/ORGANIZATION_NAME/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=MPS-test" \
--data "client_secret=NERkooqiyW8LLmlfnV28tSkZsjxxxxxx" \
--data "grant_type=client_credentials" \
--data "scope=project-45c024f4-1254-4b58-8207-4111d2xxxxxx"

Sample response​

The following example shows a successful response for an access token. The expires_in field indicates how many seconds the access token is valid.

{"access_token":"Ljjto9RbkQI64mH-wanXsiUr498eb3ng-xw-P47YGAXbJP5TvSqeuFjoRRxeJatHVN35_7jPzh8s2QEdA498CW8HvJXTp6RnR41313sEjhzg8qyXbVtf4JobrTWKXA7OHqjXp2tfxqkG_mqHBITbcuXxyZAxcVo...IwfxY9n7trMVNcSL88ok8o_BcFDCZaGWCkUnHfqUb-T6D8TOa57iihlN6H5II_A2Nek5qrCySAhaW9aszUqTgcqxe0jd5wMgvMWBBTAee7O8NPcbh63fZrYVwm1oOdlXuKT46zUs4xfzD_ex8nQdwzZWsQT_e39efiL1T3fy61hcVaxfxxx-xxx",
"expires_in":300,
"refresh_expires_in":0,
"token_type":"Bearer",
"not-before-policy":0,
"scope":"email project-45c024f4-1254-4b58-8207-4111d2xxxxxx profile"
}

You can then include the access token in the HTTP Authorization request header using the Bearer authentication scheme:

Authorization: Bearer <ACCESS_TOKEN>

Regenerate a client secret​

Unlike access tokens, client secrets do not expire.

If the client secret becomes compromised, follow these steps to generate a new client secret:

  1. In the OAuth Clients page, click Edit next to your client ID.
  2. Click on the Credentials tab.
  3. Click Regenerate Secret.

Token revocation​

info

Removing an OAuth client does not disable access tokens for that client.

If you detect a security breach, access token exposure, or unauthorized access by a third-party, contact Polaris Support to revoke your application's access tokens and delete the OAuth client.

API request example​

The following example shows how to obtain an access token for the MPS-test OAuth client and use it to authenticate to the Tables API.

import requests
import json

# Replace placeholders with your information
ORGANIZATION_NAME = "imply"
REGION = "us-east-1"
CLOUD_PROVIDER = "aws"
PROJECT_ID = "45c024f4-1254-4b58-8207-4111d2xxxxxx"

CLIENT_ID = "MPS-test"
CLIENT_SECRET = "NERkooqiyW8LLmlfnV28tSkZsjxxxxxx"

# Endpoint to obtain OAuth access tokens
TOKEN_ENDPOINT = "https://id.imply.io/auth/realms/{org_name}/protocol/openid-connect/token".format(org_name=ORGANIZATION_NAME)

access_token = None

# Tables endpoint
TABLES_ENDPOINT = "https://{org_name}.{region}.{cloud_provider}.api.imply.io/v1/projects/{project_id}/tables".format(org_name=ORGANIZATION_NAME, region=REGION, cloud_provider=CLOUD_PROVIDER, project_id=PROJECT_ID)

# Obtain OAuth access token
def obtain_token():
    global access_token
    params = {
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "grant_type": "client_credentials",
        "scope": "project-{project_id}".format(project_id=PROJECT_ID)
    }

    response = requests.post(TOKEN_ENDPOINT, data=params)
    response.raise_for_status()

    access_token = response.json()['access_token']

    return access_token

# Call the Tables API to return all tables for the specified project
def make_get(url):
    def do_get():
        headers = {
            "Authorization": "Bearer {token}".format(token=access_token),
            "Content-Type": "application/x-www-form-urlencoded"
        }
        return requests.get(url, headers=headers)

    response = do_get()

    # If the access token expired, refresh it and try the request again
    while response.status_code == 401:
        print("Refreshing token")
        obtain_token()
        response = do_get()

    # Raise an exception on response errors at this point
    response.raise_for_status()

    return print (json.dumps(response.json(), indent=4, sort_keys=True))

make_get(TABLES_ENDPOINT)

Sample response​

The following example shows a successful response:

Click to view the response
{
    "values": [
        {
            "availability": "available",
            "createdByUser": {
                "userId": "714f6ed5-e822-4e24-b8dc-b7f4a9xxxxxx",
                "username": "user1@imply.io"
            },
            "createdOnTimestamp": "2023-10-04T22:36:05.374421Z",
            "description": null,
            "id": "018afcd5-817e-74e2-a3e2-fd76e44e3737",
            "modifiedByUser": {
                "userId": "714f6ed5-e822-4e24-b8dc-b7f4a9xxxxxx",
                "username": "user1@imply.io"
            },
            "modifiedOnTimestamp": "2023-10-04T22:36:05.374448Z",
            "name": "1213",
            "partitioningGranularity": "day",
            "schemaMode": "flexible",
            "storagePolicy": null,
            "totalDataSizeBytes": 0,
            "totalRows": 0,
            "type": "detail",
            "version": 0
        },
        {
            "availability": "available",
            "createdByUser": {
                "userId": "f4139753-be18-4ef1-acc1-3b8c8exxxxxx",
                "username": "user2@imply.io"
            },
            "createdOnTimestamp": "2023-10-24T15:09:13.058954Z",
            "description": null,
            "id": "018b623b-91e2-7125-8482-1d34f6794c8a",
            "modifiedByUser": {
                "userId": "f4139753-be18-4ef1-acc1-3b8c8exxxxxx",
                "username": "user2@imply.io"
            },
            "modifiedOnTimestamp": "2023-10-24T15:10:10.259703Z",
            "name": "Test table",
            "partitioningGranularity": "day",
            "schemaMode": "flexible",
            "storagePolicy": {},
            "totalDataSizeBytes": 3441,
            "totalRows": 9,
            "type": "detail",
            "version": 1
        }
    ]
}

Store API credentials​

OAuth clients, the client ID, and the client secret for Polaris exist until you explicitly disable or delete them.

info

If your application becomes compromised, contact Polaris Support to revoke access tokens and delete the OAuth client.

Because OAuth clients grant access to your environment and your data, it is a good practice to use a secrets manager such as Vault or AWS Secrets Manager to store your OAuth credentials. At runtime you can extract the credentials from the secrets manager and make them available to your application.

For development purposes, you can put an access token in an environment variable on the machine from which the API requests originate.

For example:

export IMPLY_TOKEN="$(curl -s -d grant_type=client_credentials -d client_id={client_id} -d client_secret={client_secret} "https://id.imply.io/auth/realms/{organization_name}/protocol/openid-connect/token" | sed -e 's/.*"access_token"\s*:\s*"\([^"]*\)\".*/\1/')"

Learn more​

See the following topics for information on the Polaris API: