People sign in to the WebUI with a browser session, covered in Users, roles, and sessions. Applications use API keys for SoAI's OpenAI-compatible and Anthropic-compatible API surfaces. MCP clients use separate personal access tokens; see MCP overview for that workflow.
First run and API protection
Until the first administrator account exists, SoAI refuses protected API requests outside the setup wizard's own
endpoints with 403 and setup_required, and that includes /v1. After account
creation, the compatible API stays open only while the API-key store holds no records, and creating the first record
makes bearer authentication required for those requests.
Revoking a key or letting it expire does not reopen the API, because the store counts every record rather than only the usable ones. Select Delete all keys only when you intentionally want to remove every API-key record (including revoked or expired ones) and return the compatible API to the unauthenticated state. This does not grant or remove WebUI access.
While a key insert or deletion is in flight and its outcome is not yet known, SoAI treats protection as
indeterminate and fails closed, so /v1 returns 503 until the transaction settles and the
store recounts. The security hardening audit reports the same state, so a 503 that persists points at
the API-key registry rather than at a model or a plugin.
Create and manage a key in the SoAI WebUI
An administrator whose ACL grants API key management (OPENAI_API_ADMIN) selects the
Settings button at the right of the header, then selects Settings from its menu.
Open OpenAI. Under OpenAI server API keys, select Create key, enter
a Label (optional), and choose an Expiration. Copy the secret from the
API key created dialog before closing it, because SoAI does not show the full value again, so store
it in the client secret store rather than a project file. Every key begins with soai-, and the list
keeps its first 12 characters so you can tell which key a client uses without holding the secret.
For example:
soai-AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8
Expiration offers 90 days or Never, and Never
records no explicit expiry rather than making the key permanent. A key created without one inherits the instance
default from
API.OPENAI.SECURITY.KEY_EXPIRATION.DEFAULT_TTL_DAYS,
which ships as 90 days, so a key that must not expire needs that setting changed to 0 first.
API.OPENAI.SECURITY.KEY_EXPIRATION.ROTATION_REMINDER_DAYS
ships as 75 days and drives the Rotation due marker in the list, which is a reminder and does not
stop the key from authenticating.
In Active keys, use Rotate to issue a replacement and revoke the current key. The replacement keeps the original label and scope and shows its new secret once, and it takes the default expiration because rotation offers no expiration choice. A key that is already revoked cannot be rotated, so create a new one instead. Revoke stops a key from authenticating requests, while Delete permanently removes its record. Enable Show revoked keys when you need to audit or clean up old entries. SoAI stores a salted HMAC-derived value and fingerprint, not a reusable plaintext copy.
Set a key quota
Select Limits for a key. Choose Unlimited, Tokens, or
Requests, then set one or more hourly, daily, weekly, or monthly limits. An hourly limit also needs
its Window (hours), a rolling window that
API.OPENAI.KEY_QUOTAS.MAX_HOURLY_WINDOW_HOURS
caps at 720 hours. Assigned user appears for administrators. Assigning a user applies the key's
quota to that user's WebUI chats and attributes requests made with the key to that account without changing what
the key may do, and deleting the assigned account leaves the key unable to authenticate. Saving quota settings
resets usage tracking for that key.
Quotas cap one key's requests or tokens over a usage window. They are separate from the instance-wide request limiter, which controls request frequency by remote client address. See Rate limits and quotas for the difference and the default state.
What an API key permits
An SoAI API key carries only Public inference API access (OPENAI_API), and SoAI rejects any
other scope when a key is created or rotated. It does not give its holder a WebUI session,
administrative access, shell access, or MCP access. Configure the client with the exact authentication header and
base URL shown in the HTTP API reference. Keep the API on the private deployment boundary
described in Security hardening, and configure its transport with
Network and TLS.