Agent authentication

#Connect an account

Open the API Keys page, sign in or create an account, and complete the verification shown there. Then create a developer key for this agent. Copy it when it is shown; it is shown only once. Return to your installer to finish setup. A pending verification step requires your participation; an agent should wait for you to finish it.

For the CLI, provide the key through the installer prompt or set SOGNI_API_KEY through your runtime's secret configuration. For REST, follow the API authentication reference. Do not put the value in a prompt, URL, source file, screenshot or command saved to shell history.

#Check access

For hosted MCP, save a developer key in your client's secret configuration as a Bearer token. The hosted connection checks the key on every request and does not use the CLI's local credential store or OAuth sign-in.

For the CLI, run:

sogni-agent doctor --json

Check the individual auth result. status: "pass" means the key was accepted. A warning means access was not verified; overall success: true alone is insufficient. A successful authentication check does not guarantee model eligibility or sufficient funds.

#Key permissions and limits

Give each agent or runtime its own developer key. An account can hold up to 99 keys, and each one has its own name, usage history and optional spending limits (see API Keys):

• Spending limits. Set daily, monthly and lifetime limits, separately for Spark and SOGNI. Work the agent submits with that key is refused before anything is charged once it would pass a limit. Spark limits also count work your Unlimited plan covers, at its Spark value.
• Expiry and pause. Give a key an expiry date, or pause it and resume it later.
• Usage. The API Keys page shows each key's spend today, this month and in total, plus a 30-day chart and a per-model breakdown.

A developer key still acts for your whole account within those limits: it can spend your balance and read your account, so it is not a read-only or single-purpose grant. It cannot create, change or revoke keys; only you can, signed in to the dashboard. Your account's Original key cannot be given limits or an expiry, so do not hand it to an agent.

When a key reaches a limit, requests fail with code 4202 (daily), 4203 (monthly) or 4204 (lifetime) and a message naming the limit. An agent should stop and tell you rather than retry; raising a limit is your decision.

#If a key is exposed

Revoke it on the API Keys page, or rotate it and stop the old secret immediately. Revoking disconnects only sessions that use that key; your other keys keep working. Put the new key into every runtime that used the old one, then check the key's usage for anything you don't recognize.

Existing API-key access is not permission to charge a saved card. Fund your account through the supported user flow.