Skip to main content

Virtual API keys

A virtual API key lets someone authenticate to the gateways with a long-lived key instead of an interactive sign-in. It is the right mechanism for a script, a continuous integration job, or a tool that cannot complete a browser flow.

The key is not a shared service credential. Each key is bound to the identity of the person who created it, and when a request presents one, the platform resolves it back to that identity. Everything downstream, budgets, access decisions, and the audit trail, sees the owner rather than an anonymous key. Revoking a person's access revokes their keys with it.

Where to find them​

Every authenticated user manages their own keys in the console under API keys, no administrative grant needed. Over REST the collection is /v1/keys.

Administrators can list and disable keys belonging to other users. That is a role-gated capability rather than something every user can do.

Prerequisites​

Virtual keys require the platform's identity provider to be configured, since key issuance binds each key to a real identity. The AI Gateway also enforces this in its own configuration: enabling virtual keys without identity configured is refused rather than started in a state where keys could not be attributed.

Enabling virtual keys on the AI Gateway also deploys its management API, which the console uses. There is no separate switch for the two today, so an installation that wants the console's gateway screens needs virtual keys enabled.

Issue a key​

  1. Open API keys in the console.
  2. Create a key and give it a name that says where it will be used.
  3. Copy the value immediately. It is shown once and cannot be retrieved afterwards; only its prefix is stored for identification.

The key can then be used wherever a provider API key would go. See Connect a client.

Rotate and revoke​

Rotating issues a new value and invalidates the old one under the same key record, which keeps the name and its history. Prefer it to deleting and recreating when a key is merely old.

Revoking invalidates the key immediately. Disabling is the reversible version, useful when you suspect a key is misused but are not yet certain.

Key creation, rotation, revocation, and enable or disable changes are all recorded in the audit trail, along with the identity that made the change. See Forward audit logs.

Storage​

Keys are stored hashed, in the directory's database, alongside the users and groups they belong to. The plaintext value exists only in the response that created it. A key presented on a request is validated against the stored hash, and the gateway then acts on the owner's resolved identity.

Next steps​