API Keys

With a personal API key, your own scripts and programs can use AITEZA on your behalf, without your password. Treat API keys like passwords: whoever has a key can act in your name within the key’s limits.

There are two types of keys:

Who Can Create API Keys#

• You need the API keys role. Organization admins give it on the People page (see Roles). Like every role, it applies in all organizations you belong to. Each key, however, works in one organization only.
• With the role, Settings shows the API keys page in the Personal section, and on the My account page You can lists “Create personal API keys”. If the page does not appear after you were given the role, sign out and sign in again.
• If the page says “API keys are not switched on”, your installation does not offer personal API keys. Contact the operators of your installation.

The Two Key Types#

AITEZA API#

An AITEZA key calls the AITEZA REST API as you, in the organization you were working in when you created it. It can never do more than you may do yourself, and it acts like a plain member of this organization:

• No admin roles. Your admin roles (Organization admin, Dataroom admin, platform administrator) do not apply to the key. It reaches only the datarooms in which you are an owner, editor or viewer, directly or through a group, not every dataroom of the organization.
• Only this organization. The key does not see your other organizations. For example, GET /api/identity/me/tenants lists only the key’s organization.
• All your chats and files. Your own chats and your own files, the ones you uploaded and the ones AITEZA generated for you, are not tied to an organization in AITEZA. The key can therefore read all of them, including those from your other organizations. A key with Read and write can also change and delete them.

If your access changes, the key follows.

When you create the key, you choose its access:

What a key with Read may do depends on the HTTP method of the request. Everything that creates, changes or deletes something, including sending a chat message, needs Read and write. So do some functions that only retrieve data but send their request with POST, for example a search in datarooms.

Requests to AI models made with an AITEZA key, for example chat messages, count as your usage, just like your requests in the browser.

LiteLLM, OpenAI-compatible#

A LiteLLM key gives OpenAI-compatible programs direct access to the AI models through https://<your AITEZA host>/v1. Many tools and libraries that work with the OpenAI API work with it: you set the base URL and the key.

• Only your models. The key can use the models you may use in the organization, including the selection of your groups (see Which Models a Person Can Use). If that changes, the key follows. Use the model names that /v1/models lists; they can differ from the names in AITEZA’s model selection.
• Only model calls. The key can call and list the models, but no other functions such as files, batches or assistants (see Calling the Models with a LiteLLM Key).
• Monthly limit. Your organization admins set how much each person may spend with LiteLLM keys per month. The limit applies to you, not to each key: it covers all your LiteLLM keys in the organization together, including keys that were revoked or expired this month. The API keys page shows your limit and what your keys have spent this month (see The API Keys Page). Once your keys have used up the limit, their requests are refused until the limit starts again at the beginning of the next month. You can still create LiteLLM keys, but they share the same limit.
• Costs. Requests with your LiteLLM keys appear on your My usage page and on the organization’s Usage page under your name.
• Availability. You can choose this type only if your installation offers LiteLLM keys and your organization admins have set a monthly limit. Otherwise the option is disabled and shows the reason: “Not available on this installation” or “Your organization has not set a limit yet”. You also need at least one model you may use in the organization.

AITEZA keys do not work at /v1, and LiteLLM keys do not work with the AITEZA API.

The API Keys Page#

Open the profile menu, select Settings and then API keys in the Personal section. The page shows your keys in the organization you are currently working in (see Working in Several Organizations):

• Active with the number of keys, for example “Active (2)”: the keys that can be used.
• Expired or revoked: keys that have ended. They stay visible for 30 days after they end.

If your organization offers LiteLLM keys, the page also shows your monthly limit for them and what all your LiteLLM keys have spent this month together, for example “Monthly limit for your LiteLLM keys: €25.00 · €3.10 spent this month”.

Each key shows:

• its name,
• the type (AITEZA API or LiteLLM) and the beginning of the key, for example azk_AbC1dEf2… or sk-azp-AbC1dEf2…, so you can tell keys apart,
• for AITEZA keys the access (Read or Read and write), for LiteLLM keys what this key has spent this month, for example “€3.10 spent”,
• when it was created, when it expires (“Expires on …”) or ended (“Expired on …”, “Revoked on …”), and when it was last used (“Last used on …” or “Never used”).

Creating a Key#

The dialog starts with AITEZA API, Read and 90 days. Choose the shortest validity that fits; 30 days is the safest.

• The name can be up to 100 characters long and must differ from the names of your other active keys.
• You can have up to 10 active keys at the same time, counted across all your organizations, unless your installation sets a different number.
• A key cannot be extended. Before it expires, create a new key, switch your program over to it and revoke the old one.
• To use a key in another organization, switch to that organization first and create a key there.

If AITEZA cannot create the key, the dialog says why:

The Key Is Shown Only Once#

While the key is shown, clicking outside the dialog or pressing Escape does not close it, so you cannot lose the key by accident. Close the dialog with Done once you have stored the key.

Below the key, How to use the key shows a first call to try, with the right address of your installation. Copy example copies it. For a LiteLLM key, the dialog also shows the Base URL for OpenAI-compatible programs.

Keeping Keys Safe#

• Store the key in a password manager or in the secret store of the system that runs your program.
• Hand it to your program in an environment variable, for example AITEZA_API_KEY or OPENAI_API_KEY, not as part of the program.
• Never put a key into source code, configuration files under version control, chat messages, emails, tickets or prompts. Do not pass it on: everyone who needs a key creates their own.
• Use one key per program or purpose, so you can revoke one without affecting the others.
• Keep in mind that an AITEZA key reaches all your own chats and files, also those from your other organizations (see AITEZA API). Whoever has a key with Read and write can also change and delete them.
• Choose Read and the shortest validity that fits.
• If a key may have become known to others, revoke it immediately.
• Resetting your password does not revoke your keys. If your account may have been compromised, revoke your keys or ask an organization admin to select Sign out everywhere for you, which also revokes all your keys.

Using a Key#

The examples use aiteza.example.com. Replace it with the address of your AITEZA; the dialog after creating a key shows the right address. The examples expect the key in an environment variable. To set the variable without the key ending up in your shell history, enter for example:

read -rs AITEZA_API_KEY && export AITEZA_API_KEY

Then paste the key and press Enter. The key does not appear on the screen.

Calling the AITEZA API#

Send the key as a bearer token in the Authorization header. This call lists the models you may use:

curl https://aiteza.example.com/api/models \
  -H "Authorization: Bearer $AITEZA_API_KEY"

You can also send the key in the X-API-Key header:

curl https://aiteza.example.com/api/models \
  -H "X-API-Key: $AITEZA_API_KEY"

To try the endpoints in the browser, open the API reference at https://<your AITEZA host>/doc/swagger-ui.html, select Authorize and enter the key under api_key. Endpoints that keys cannot use list only the Keycloak sign-in there.

• Send exactly one key per request and no other sign-in token with it.
• You do not need to choose an organization: the key always works in its own. If your program sends the X-Tenant-Id header anyway, it must name the key’s organization.
• Each key may make at most 60 requests per minute, unless your installation sets a different number. Further requests are refused with 429 (see Error Messages).
• Your installation can also set a generous limit per person. It applies to all your requests together, with every key and signed in to AITEZA, and limits the requests per minute and the requests running at the same time. When it is on, every response names the requests still available and the seconds until all are available again in the RateLimit header; RateLimit-Policy names the limit itself.
• What you do with the key is recorded in the Audit Log under your name. The event details name the key (apiKey and apiKeyName). Requests that AITEZA refuses because of the key’s limits, for example an administrative function, another organization or a change with a Read key, are recorded as “Access denied”, so the misuse of a lost key shows up.

Calling the Models with a LiteLLM Key#

Use https://<your AITEZA host>/v1 as the base URL. Many OpenAI-compatible programs read the key from the environment variable OPENAI_API_KEY by themselves. This call lists the models the key may use:

curl https://aiteza.example.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

A chat request, with one of the listed model names in place of MODEL_NAME:

curl https://aiteza.example.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "messages": [{"role": "user", "content": "Hello"}]}'

The same with the OpenAI library for Python (pip install openai):

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://aiteza.example.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

• Send the key exactly once, as Authorization: Bearer sk-azp-…. The OpenAI client libraries do this by themselves. Other ways of sending it are refused with 401, for example the key in the address, the key twice, Basic instead of Bearer, or another header with additional text.
• The key can only call model endpoints: chat completions, completions, responses, embeddings, the model list, moderations, rerank, audio (transcriptions, translations, speech) and images (generations, edits, variations). Other endpoints, for example files, batches, vector stores, assistants, fine-tuning or MCP, are refused with 403.
• Request bodies, except file uploads, must be a single JSON object without duplicate fields, and the model must be one of your models. LiteLLM’s automatic fallback to other models is switched off for these keys.
• Each LiteLLM key can run at most 4 requests at the same time, and all your LiteLLM keys in the organization together can make at most 60 requests per minute, unless your installation sets different numbers.

What Keys Cannot Do#

AITEZA keys have these limits, whatever their access:

• No administration. A key cannot use the organization administration (/api/admin/…), the platform administration (/api/platform/…) or some other administrative functions. Your admin roles (Organization admin, Dataroom admin, platform administrator) and any admin rights do not apply to requests made with a key.
• No key management. A key cannot create, list or revoke API keys. You manage keys only on the API keys page.
• No workflows. Workflows cannot be started with a key, neither directly nor through a chat message. Run workflows in AITEZA while signed in.
• Read keys do not write. A key with Read access accepts only GET, HEAD and OPTIONS. Every other method is refused, and the key cannot create anything, not even a chat.
• One organization. A key works only in the organization it was created in. Only your own chats and files are reachable across organizations (see AITEZA API).
• At most 60 requests per minute. Further requests are refused until the time given in the Retry-After header has passed. Your installation can set a different number.

LiteLLM keys can only call model endpoints, and only with your models (see Calling the Models with a LiteLLM Key).

When a Key Stops Working#

• It expires at the end of its validity.
• You or an organization admin revoke it.
• An organization admin signs you out everywhere, disables your account or takes away the API keys role. This revokes all your keys, in every organization. Removing you from an organization revokes your keys in that organization.
• You lose access in another way, for example because your account is disabled, the role is taken away or you leave the organization directly in the identity management (Keycloak) of your installation. Your keys are then refused within about a minute and revoked within 15 minutes.
• The operators of your installation switch API keys off. Keys that were neither revoked nor expired work again once API keys are switched back on.

Revoked keys stay revoked: getting your access back does not bring old keys back, so create new ones. Resetting your password does not revoke your keys.

Revoking a Key#

Programs using the key lose access immediately. This cannot be undone. The key moves to Expired or revoked and stays visible there for 30 days. A revoked LiteLLM key is also deleted in LiteLLM.

Organization admins can revoke your keys as well (see Revoking Someone’s Key).

Error Messages#

When AITEZA refuses a request made with an AITEZA key, it answers with an HTTP status and a JSON body with a code and a short message, for example:

Other answers mean the same as in AITEZA itself, for example 404 for something that does not exist.

Requests with a LiteLLM key to /v1 are answered in the error format of the OpenAI API, with the explanation in error.message:

When your LiteLLM keys have used up your monthly limit, LiteLLM itself refuses further requests with status 400 and a message about the exceeded budget, until the limit starts again at the beginning of the next month. LiteLLM also refuses requests beyond the limits on parallel requests and requests per minute.