Create Virtual Keys for Apps and Agents

• One key per app, agent, or environment
• Labels that drive policy and reports
• A test from the console
• A rotation and revocation routine

You need an owner or admin role. Provider credentials come from the previous guide.

1. 1

   Choose + Create Key

   It is at the top of the Virtual Keys card.

2. 2

   Enter a Key name

   Say what and where, such as support-chatbot-prod.

3. 3

   Set Valid for (days)

   Choose a lifetime that fits your rotation habit. The default is 3,650 days.

4. 4

   Set the default Team ID, App ID, and Environment

   These labels travel with every request the key makes.

5. 5

   Optionally set an Upstream credential override

   Override which provider credential the key uses, for all providers or for particular ones.

6. 6

   Create and copy the secret

   It is shown once. Store it in your secret manager.

• They choose which policy applies, through the bindings you set
• They label spend, blocks, and errors in the Explorer
• They are set once on the key, so every call carries them

Request headers such as x-cloptima-team label usage but cannot move a key onto a different policy. The key decides.

1. 1

   Open Test Virtual Key

   It is at the bottom of the Virtual Keys card.

2. 2

   Select the key

   A key you just created is ready to use.

3. 3

   Enter a model and a prompt

   Use something short.

4. 4

   Choose Send Test Call

   You see the answer, or the block reason if a policy applies.

from openai import OpenAI

client = OpenAI(base_url="https://api.cloptima.ai/v1/ai", api_key="clop_vk_...")
reply = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello"}],
)

A virtual key can only call models through the gateway. It cannot change settings or read your data.

1. 1

   Choose Rotate on the key

   Set a new name or lifetime if you want one.

2. 2

   Copy the new secret

   It is shown once.

3. 3

   Update your app

   Deploy the new secret.

Use it when a key may have leaked, when an app is retired, or when a person leaves a team. Spend history stays in the Explorer under the key's name.

Use a telemetry key when your app calls a provider directly and reports usage to Cloptima, and a virtual key when your app calls through the gateway.