Add and Rotate Provider API Keys

Maxi’s AI features — generating text and images — run through external AI providers. To use them, you give Maxi an API key for each provider you want. This guide covers adding keys, replacing them safely, and checking their status — all done through your agent.

Maxi doesn’t generate text or images itself; it calls an external AI provider to do that, using an API key you supply. You only need keys for the providers you actually intend to use. The supported providers are OpenAI, Anthropic, OpenRouter, Replicate, BFL (Black Forest Labs), and a “local” option for a self-hosted endpoint.

Today, keys are managed through your agent — you ask it to set or rotate a key in conversation. Before doing that, it’s worth understanding how Maxi protects them and one caution that’s in your hands.

How your keys are protected

• Encrypted at rest. Every key you give Maxi is encrypted before it’s stored. It’s never kept in plain text in your database.
• Only ever shown masked. After you set a key, Maxi never displays it in full again — to you or to the agent. You’ll only ever see a masked form like sk-proj-…Q_IA.
• One caution that’s yours to manage. Because you set a key by giving it to the agent, the key passes through that conversation — and your AI client (ChatGPT, Claude, etc.) may keep it in its chat history, which is outside Maxi’s control. If that concerns you for a particular key, the clean remedy is to rotate that key at the provider afterward, so the value that appeared in chat is no longer valid. Treat provider keys like any other secret you’d be careful pasting into a chat.

Adding a key

Ask your agent to set the key for the provider you’re using. For example:

“Set my OpenAI API key to <your key>.”

The agent stores it (encrypted) and it’s immediately available for generation. For the local option, you provide an endpoint URL instead of a key.

Note that adding a key this way stores it as given — Maxi doesn’t test it at the moment you add it. The simplest way to confirm it works is to run a small generation, or check its status (below) after first use. If you want Maxi to test before saving, use rotation instead — see below.

Checking key status

You can ask your agent for an overview of your keys at any time. This is always safe — it never exposes the secret, only masked prefixes and usage information:

“Show me the status of my AI provider keys.”

For each provider you’ll see whether a key is set, a masked prefix, when it was last rotated, how old it is, when it was last used, and whether the last call succeeded or errored. This is the quickest way to answer “is my key working?” or “which provider handled that last job?”

A key is flagged stale once it’s more than 180 days old — a nudge to refresh it, not a sign anything’s wrong.

Rotating a key — the safe way to replace one

Rotating means swapping in a new key — because the old one is aging, may have been exposed, or you’re changing accounts. Rotation has an important safety property that plain adding doesn’t:

Maxi validates the new key with a live test call before replacing the old one. If the new key fails the test, the old key stays in place and nothing breaks — you’re simply told the new one didn’t validate. A bad paste can’t lock you out.

To rotate, ask your agent:

“Rotate my OpenAI key to <new key>.”

Because of the validate-first behaviour, rotation is the more robust way to put a new key in place — if you want certainty that a key is good before it goes live, rotate rather than plain-add.

If a key stops working

If generation suddenly fails for one provider, check that key’s status first (ask the agent, as above) — the last error will often tell you why. Common causes: the key was revoked or expired at the provider, billing lapsed on the provider account, or the key was changed elsewhere. The fix is to set or rotate a fresh key, as above.

In summary: Maxi uses your own API keys to reach AI providers (OpenAI, Anthropic, OpenRouter, Replicate, BFL, or a local endpoint), and you manage them by asking your agent. Keys are encrypted and only ever shown masked. Adding a key stores it as-is; rotating a key tests it live before replacing the old one, so it can’t lock you out — prefer rotation when you want certainty. Ask your agent any time for key status; it shows masked prefixes and usage, never the secret. Keys over 180 days old are flagged stale as a reminder to refresh. Because keys are entered in conversation, rotate at the provider afterward if you’re concerned about a key lingering in your AI client’s history.