M↓ View as Markdown ↗

API Keys¶

API keys authenticate requests to the Public API. AI Analyst issues and stores them itself; they don't come from your identity provider.

Availability

Who can do this: members with the Manage organization capability. See Members for how access is granted; the Admin role includes this capability.
Deployment: Actian SaaS and self-managed deployments.

Members without Manage organization don't see API keys in Settings.

One key, one Workspace¶

Each key is bound to one Workspace when you create it. You can't change that later.

Requests made with the key can export and import only that Workspace's semantic layer (models, metrics and glossary terms) and AI Analysts.
A key can't administer your organization.
A Workspace can have several keys. To automate more than one Workspace, create a key for each.
Deleting a Workspace also deletes all of its keys, including active ones. When you delete a Workspace, the confirmation dialog shows how many API keys will be deleted with it.

Note

The UI sometimes says Environment where this documentation says Workspace. For example, the API keys page subtitle reads "Issue keys bound to one Environment for the Public API." The same wording appears on Settings → Import / export.

Create an API key¶

Go to Settings → API keys (under Administration). You can open Settings from Studio or Explorer.
Click Create API key.
If your organization has more than one Workspace, choose the Workspace the key will work in. The default Workspace is selected to start with.
Enter a Name (required, up to 100 characters). Choose something that identifies the integration, such as CI/CD Pipeline or Nightly backup. The name is what appears in Audit.
Optionally add a Description (up to 500 characters).
Optionally set an Expiry date. Leave it empty for a key that never expires.
Click Create.
Copy the Secret with the copy button, then click Done.

The secret starts with aia_ and is shown only once ("This secret will not be shown again."). AI Analyst stores only a hash of it, so nobody can view it later. If you lose it, revoke the key and create a new one.

About the Expiry date:

The key stops working at 23:59:59 on the chosen day, in the time zone of the browser you created it in.
The date must be today or later and no more than ten years away. If you pick a later date, Create stays disabled.

Warning

Treat an API key like a password. Store it in a secrets manager or a CI/CD secret variable, and never commit it to source control.

Use an API key¶

Send the secret as a Bearer token in the Authorization header:

Authorization: Bearer aia_...

For example, to export the key's Workspace as a Lossless zip:

curl "https://<your AI Analyst host>/api/public/v1/environment" \
  -H "Authorization: Bearer $AI_ANALYST_API_KEY" \
  -o export.zip

See Public API for the base URL, endpoints, rate limits and errors. The Public API docs link on the API keys page opens the interactive reference on your own AI Analyst host.

View your keys¶

Settings → API keys lists every key in your organization, across all Workspaces, newest first.

Column	What it shows
Name	The name you gave the key.
Last used	When the key last made a request, or Never. Updated at most once a minute.
Expires	The expiry date, or Never.
Status	Active, Expired or Revoked. Only active keys work.
Created by	The member who created the key.

The list doesn't show a key's description or the Workspace it is bound to, so include the Workspace in the key's name if you have several.

Revoke a key¶

Go to Settings → API keys.
Click Revoke next to the key.

The key stops working immediately. There is no confirmation step, so make sure the right key is selected. Revoke is available only for active keys.

To rotate a key without downtime, create the new key first, update your integration to use it, and then revoke the old key.

Delete a key¶

Once a key is Revoked or Expired, click Delete to remove it from the list. There is no confirmation step. You can't delete an active key; revoke it first.

Audit trail¶

Creating, revoking and deleting a key are recorded in Audit under the member who did it.
Exports and imports made with a key are recorded with the member who created the key as Initiator and the key, shown by its name (for example CI/CD Pipeline), as Executor.
Keys removed because their Workspace was deleted don't get their own entries; the Workspace deletion is recorded instead.

When keys stop working¶

Situation	Effect on API requests	Effect on the API keys page
The key is revoked or past its expiry	Refused with `401`	Status shows Revoked or Expired
The organization is pending deletion or being closed	Refused with `403`	You can view, revoke and delete keys, but not create them
The organization's access is on hold, or its trial has ended	Refused with `403`	The page can't be used: you can't view, create, revoke or delete keys
Self-managed deployment whose licence has expired	Exports keep working; imports are refused with `403`	The page can't be used

A key keeps working when the member who created it leaves the organization or loses the Manage organization capability. When someone who manages integrations leaves, review the keys they created and rotate or revoke them.

Security recommendations¶

Create a separate key for each integration and Workspace, so you can revoke one without affecting the others.
Set an Expiry date and rotate keys regularly.
Revoke a key as soon as you suspect it has been exposed, and check Audit for requests made with it.
Review the Last used column and revoke keys that are no longer in use.

Troubleshooting¶

I can't see API keys in Settings. You need the Manage organization capability. If you open the page's address directly without it, you see "Studio access is required to manage API keys." Ask an organization administrator to grant the capability or create the key for you.

Create stays disabled. Check that Name isn't empty and that the Expiry date is no more than ten years away.

My requests return 401. Check that the header is exactly Authorization: Bearer <secret>, that you copied the whole secret, and that the key's status is Active.