Skip to main content

API keys

API keys let your own tools and integrations call Mother's APIs without sharing your login.

Creating and managing keys​

Owner and Users can create keys from Settings → API keys (or programmatically through the auth API):

  1. Create a key; it is shown once — store it somewhere safe.
  2. Keys carry the permissions of the account that created them.
  3. Revoke a key at any time from the same place; calls using it fail immediately.

Using a key​

Send it as a Bearer token on any authenticated endpoint:

Authorization: Bearer <your-api-key>

That covers the OpenAI-compatible endpoints, the native API (chat, files, search, models), and WebSocket connections.

How Genesis uses keys​

You normally do not manage keys for Genesis itself — the workspace provisions the credentials it needs automatically:

  • When you start a Genesis session, it uses your signed-in identity; no separate key is required.
  • When an integration or agent needs programmatic access (for example a subagent calling the inference API), Genesis auto-creates a key scoped to that need and uses it transparently. You will see these keys in Settings → API keys, marked as created by Genesis.
  • If you revoke a Genesis-created key, Genesis recreates it on the next run. Revoke deliberately: anything relying on the old key stops until then.

Token refresh, in brief​

Login-based access uses short-lived access tokens renewed by a refresh token (rotate-on-refresh: after a refresh, the old pair is invalid). API keys do not expire this way — they last until revoked. Programs that log in directly should handle 401 access token expired by calling POST /v1/auth/refresh and replacing both tokens.