Managing API Keys

API keys are the credentials your code uses to call the AIOZ AI API. This page covers what you do with them (creating, naming, renaming, revoking, rotating), plus how to organize keys across environments and teams, and where the model deliberately stops.

For what an API key is and how it's sent in a request, see Authentication.

Where to find your keys

There are two management screens, both under the API Keys sidebar entry:

Personal keys live in your user settings.
Organization keys live in the organization's settings. This screen is visible only to the organization's owner; other members don't see the entry at all.

A user who belongs to several organizations sees one personal-keys screen plus one organization-keys screen for each organization they own. Each kind of key is billed to a different account, so pick the right scope before you create. See Authentication for the personal-vs-organization distinction and How Billing Works for cost attribution.

Planning your keys

There's no limit on the number of keys, and most teams use several. The patterns that work:

One key per environment (local, staging, production): revoke one without touching the others.
One key per service: retire or rebuild a service by revoking just its key.
One key per developer for local work: no shared-key scramble when someone joins or leaves.

These combine: a small team often has one personal key per developer plus a few organization keys for shared services. Avoid one key shared across many places; rotating it means coordinating every integration at once, and any single leak compromises all of them.

Creating a key

From the API Keys screen, click Add new API key and give it a name. The key value is shown as soon as the key is created.

Naming. The name is what you'll see throughout the UI and in logs. Pick something specific: local-dev-alice, staging-server-east, and chatbot-prod are good; key1, test, and api are not. A convention like <environment>-<service> makes lists easier to skim and rotation easier to coordinate. Constraints:

3 to 64 characters.
Letters, numbers, spaces, hyphens, and underscores only.
Unique within a single scope (your personal keys, or one organization's keys).

Right after creation, the key appears at the top of the list and is immediately usable. Copy the value into wherever it will live (environment variables, secrets manager, CI config); see Authentication for storage guidance, then verify it with a quick account-balance call (Quickstart step 2). You can copy the value again later, but a fresh key is the easiest moment to wire everything in cleanly.

Renaming a key

Open the row's actions menu, choose Rename key, edit, and save. The same name rules apply. Renaming changes only the label; it doesn't change the key value, invalidate it, or interrupt anything currently using it.

Revoking and rotating keys

To revoke, open the actions menu and choose Delete key, then confirm. Revocation is immediate and permanent: no recovery, no undo, no grace period. The next request that authenticates with the revoked key fails with an authentication error.

There is no separate "regenerate" or "rotate" operation: rotation is just revoke + create.

Zero-downtime rotation

Because revocation is immediate, rotate by creating before you destroy:

Create a new key alongside the old one.
Deploy it to every integration using the old key.
Verify traffic is flowing on the new key.
Revoke the old key.

Both keys are valid during the overlap, so nothing breaks mid-rotation.

When to revoke

A key is exposed (committed to a repo, pasted into chat, found in a log). Revoke immediately and rotate; a leaked value can't be scoped down, only made worthless. The sooner you revoke, the smaller the window for misuse.
An integration is retired (a service shut down, a developer left, a one-off pipeline finished). Revoke its key rather than leaving a valid credential around.
Scheduled rotation as routine hygiene, regardless of any known problem. Many teams rotate production keys quarterly; the cost is one zero-downtime rotation, and it bounds the impact of an unnoticed leak.

Working with organization keys

Organization keys differ from personal keys operationally:

Only the owner manages them. Members can't see the API Keys screen at all; creating, renaming, and revoking all go through the owner.
They survive personnel changes. A personal key belongs to a user and leaves with them; an organization key belongs to the organization and keeps working regardless of who comes and goes, as long as someone has owner access.

(Cost and usage roll up to the organization rather than to whoever made the call; see Authentication and How Billing Works.)

The typical pattern: the owner creates organization keys for anything that should outlive an individual contributor (production backends, scheduled pipelines, customer-facing apps), while developers use personal keys for local work and experimentation. When a member leaves, their personal keys go with them and the organization keys stay under the owner's control; as a precaution, the owner can rotate any organization keys the departing member knew about, following the zero-downtime pattern above.

What the model intentionally keeps simple

A few things you might expect that AIOZ AI doesn't offer, kept simple on purpose:

No per-key scopes or permissions. A key inherits whatever its owner can do. For different levels of access, give different services different keys and revoke selectively.
No expiration or auto-rotation. Keys are valid until you revoke them; run scheduled rotation on your own cadence (see the zero-downtime pattern above).
No "regenerate" action. A key's value never changes its identity or history; rotate with revoke + create.
No service-account or machine-identity concept. A key represents a real user or organization. Approximate a service account with an organization key owned by the service's organization.