Managing API Keys

API keys are the credentials your code uses to call the AIOZ AI API. This page covers everything you do with them in the web UI (creating, naming, renaming, revoking, rotating), plus guidance on how to organize keys across environments, services, and teams, and where the model stops so you can plan around it.

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

Where to find your keys

There are two separate management screens, depending on which kind of key you're working with:

Personal keys live in your user settings, under the API Keys entry in the sidebar.
Organization keys live in the organization's settings, under the API Keys entry in the sidebar. This screen is visible only to the organization's owner; other members of the organization will not see the entry at all.

Each screen lists every key in that scope, sorted with the newest at the top, and shows for each key:

Name. The label you gave it on creation.
Key. A preview of the value, with the rest hidden. The full value is never displayed in the list.
Created. When the key was made.
Actions. Copy, Rename, and Delete, accessible per row.

The Copy action on each row places the full key value on your clipboard. Unlike platforms that show a key once and then hide it forever, AIOZ AI lets you copy any key's value back any time, so there's no need to back up the value yourself.

A common point of confusion: a user who belongs to several organizations sees one "personal keys" screen for themselves, plus one separate "organization keys" screen for each organization they own. Calls made with each kind of key are billed to a different account (your personal account for personal keys, the relevant organization for that organization's keys), so picking the right scope before you create matters. See How Billing Works.

Planning your keys

There's no built-in limit on the number of keys you can have, and most teams end up with several. A few patterns that work well:

One key per environment. Separate keys for local, staging, and production keep accidental cross-environment calls from happening, and let you revoke one without touching the others.
One key per service. If multiple services in the same environment talk to the API, give each its own key. When you retire or rebuild a service, you can revoke just its key without disturbing the others.
One key per developer. For personal use during development, each developer using their own key avoids "who has the shared key" scrambles when someone joins or leaves.

In practice these combine. A typical small team often ends up with: one personal key per developer (for local work), plus three or four organization keys for shared services like staging-server, production-api, and overnight-pipeline. Each can be rotated, revoked, or audited independently.

The pattern to avoid is a single key shared across many places. Rotating it then means coordinating updates across every integration at once, and a leak from any one of them puts all of them at risk.

Creating a key

From the API Keys screen, click Add new API key. You'll be asked to give it a name; the key value itself is generated server-side and shown to you as soon as the key is created.

Choosing a good name

The name is what you'll see throughout the UI and (later) in any logs or audit trails. Pick something specific enough that future you, looking at a list of eight keys six months from now, will know which one is which. local-dev-alice, staging-server-east, data-pipeline-overnight, and chatbot-prod are good names; key1, test, and api are not.

If you're using a naming convention across your team, lean into it. A common shape is <environment>-<service> (production-chatbot, staging-recommender) or <service>-<purpose> (chatbot-incoming-webhook). Anything consistent makes a list of keys easier to skim and rotation easier to coordinate.

A few constraints to be aware of:

Names must be 3 to 64 characters.
Only letters, numbers, spaces, hyphens, and underscores are allowed.
Within a single scope (your personal keys, or one organization's keys), each name has to be unique. If you try to reuse a name, you'll get an error and can pick another.

What to do right after creation

Once you submit, the new key appears at the top of the list and is immediately usable. Two things are worth doing right away:

Copy the value into wherever it will live: your environment variables, your secrets manager, your CI configuration, your .env file. Setting it up immediately means you don't have to come back later and risk pasting the wrong key into the wrong place. See Authentication for the recommended storage approach.
Verify the key works. A quick account.balance call confirms that the key is valid and that you're hitting the API from the environment you intended. See the Quickstart step 2 for the snippet.

You can always come back later to copy the value again if needed (the UI keeps it available), but a fresh key is the easiest moment to wire everything in cleanly.

Renaming a key

Open the row's actions menu and choose Rename key. Edit the name and save. The same name rules apply (3 to 64 characters; letters, numbers, spaces, hyphens, underscores; unique within scope).

Renaming doesn't change the key value, doesn't invalidate it, and doesn't interrupt anything that's currently using it; only the label changes. Common reasons to rename are when the service a key serves gets renamed, when the key's purpose shifts over time (a key first used for prototyping is now powering a real service), or when you adopt a new naming convention across the team and want existing keys to match.

Revoking and rotating keys

To revoke a key, open its actions menu and choose Delete key, then confirm. Revocation takes effect immediately and is permanent: there is no recovery, no undo, and no grace period. The next request that authenticates with the revoked key will fail with an authentication error.

There is no separate "regenerate" or "rotate" operation. Rotation is just revoke and create, performed in whichever order is safe for what you're rotating.

The zero-downtime rotation pattern

When you need to rotate a key without taking your integration offline, do it in this order:

Create the replacement key, giving it a clear name (for example, production-2026-05).
Update your integration's configuration to point at the new key, and roll the change out everywhere the old key was used.
Wait a moment to confirm that traffic is flowing on the new key (a successful response, a log line, a usage metric, or whatever signal you have).
Revoke the old key.

If you flip the order (revoke first, then create), any request in flight or any service that hasn't been redeployed yet will start failing the instant you revoke.

A softer variant is to skip step 4 indefinitely: create a new key, migrate services to it, and leave the old key alone until you're sure nothing depends on it anymore. This is useful when you've inherited a key with no clear owner and you want to move off it cautiously. Just remember to come back and revoke it eventually; every unrotated key in your account is an unnecessary attack surface.

When to revoke

The two clear-cut cases:

A key has been exposed. Committed to a public repo, pasted into a chat, sent in an email, found in a log file: revoke immediately and rotate. There's no way to retroactively "scope down" a key once it's leaked; the only safe move is to make the leaked value worthless. The sooner you revoke, the smaller the window in which someone else could use it.
An integration is permanently retired. When a service is shut down, when a developer leaves, when a one-off pipeline finishes: revoke the key it was using rather than leaving it around. Unused keys don't help anyone, and they continue to be valid until you explicitly revoke them.

There's also the routine case: scheduled rotation as a precaution, regardless of whether anything is known to be wrong. Many teams rotate production keys quarterly. The cost is low (one zero-downtime rotation), and it bounds the worst-case impact of a key being leaked without anyone noticing.

In-flight tasks that were submitted before the key was revoked continue to run on the AIOZ network. Revoking the key prevents new calls, but doesn't reach back and cancel tasks already accepted. If you also want to stop running work, cancel those tasks explicitly (see tasks.cancel in the API Reference).

Working with organization keys

Organization keys differ from personal keys in three concrete ways:

Only the organization's owner can manage them. Members can't see the API Keys screen at all. Creating, renaming, and revoking organization keys all go through the owner.
Cost and usage are attributed to the organization, not to whoever made the call. This is the main reason teams use organization keys for shared services: billing rolls up cleanly even if the developer who set up the integration leaves.
They survive personnel changes. A personal key belongs to a specific user; if that user leaves the platform, their personal keys go with them. An organization key belongs to the organization itself, so it keeps working regardless of who comes and goes (as long as someone has owner access to manage it).

The typical team pattern is: the owner creates organization keys for any service that should outlive any individual contributor (production backends, scheduled pipelines, customer-facing apps), while developers use their own personal keys for local development and one-off experimentation. Day-to-day exploration doesn't depend on the owner being available; production traffic clearly rolls up to the organization.

When a member leaves the organization, their personal keys go with them and continue to work for whatever they personally own. They lose access to the organization, so the organization keys themselves remain safe (the owner controls them). 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 from an API-key system that AIOZ AI doesn't currently offer, kept simple on purpose:

No per-key scopes or permissions. A key inherits whatever its owner can do, period. If you need different "levels of access," do it by giving different services different keys and revoking selectively, not by trying to constrain a single key.
No expiration or auto-rotation. Keys are valid until you revoke them. If you want scheduled rotation, run it on your own cadence; see the zero-downtime pattern above.
No "regenerate" action. Rotating is always revoke + create. This keeps the model predictable: a given key value never changes its identity or its history.
No service-account or machine-identity concept. A key represents a real user or a real organization. Service accounts can be approximated by using an organization key for the service, owned by whichever organization the service belongs to.

If you're looking for one of these capabilities and don't see it, the workaround is usually some combination of creating more keys (for separation), naming them well (for clarity), and rotating them on your own schedule (for hygiene).