5 · Your account, keys and the console¶
Everything you do with Stalwart is done with an API key, and every key after the first is yours to make in the web console. This chapter is how an account is opened, how the console is reached, what each of its pages does, who may do what, and how to look after a key: mint it, store it, rotate it, revoke it, and what to do when one leaks or every one is lost.
Opening an account¶
Register your interest on the website's register-interest page; we write back with your access. You then open your account from the console's sign-in page, with Google or with an emailed link.
- With Google, you are asked for your verified address and nothing else.
- With an emailed link, you type your address and a link is mailed to it from
noreply@mail.stalwart.it. A sign-up link lasts thirty minutes and can be followed once. Nothing is created until it is followed.
The first time you sign in, your free organisation is made for you, named after your address (rename it on Account), and you own it; continuing on the sign-in page accepts the terms and the data-processing addendum, and the versions you accepted are recorded. The developer console opens on its Overview. An organisation has no key until you make one on Keys, or until a bot is first run: a key is shown once, when it is made, so copy it then; nobody, us included, can show it again. What the free plan includes, and what paying adds, is in chapter 40.
An enterprise account is opened under contract: choose Enterprise plan on the website's
Contact page, or write to newaccounts@stalwart.it.
Behind the page, the website posts your address to POST /v1/signup, which needs no key and mails the link; a
sign-in link asked for an address with no account is sent as a sign-up link. Past five links an hour to one
address, twenty to one network or two hundred to one domain, the answer carries a proof-of-work puzzle, which
a browser solves in a second or two; GET /v1/signup/challenge hands one to a page that knows it will need
it. Sign up with Google is GET /v1/signup/google, which asks Google for your verified address and nothing
else.
The console¶
The console is at api.stalwart.it/console. Three ways in, one session:
- Google, at the same verified address you signed up with;
- an emailed link, valid fifteen minutes for a sign-in;
- a live API key, pasted in. It is checked as the API checks it and never stored. A test key cannot sign in: a test key is the weaker credential, and letting it manage your live keys would make it the stronger one.
A person who belongs to several organisations chooses one after signing in. The session is one cookie that keeps this browser signed in for thirty days from the last time you used it; Sign out ends it everywhere at once. A session opened with a key reads that key again on every request, so revoking the key ends its console sessions within a minute. Every sign-in failure shows the same page with the same sentence, whatever the cause, so it tells nobody guessing which part of their guess to keep.
The sign-in page is /console/login. Its e-mail form posts to /console/login/email, under the same limits
as signing up. The link it mails opens /console/link, a page with one button, and nothing is spent until you
press it, so a mail scanner that follows the link signs nobody in. A browser asked for a puzzle first is sent
to /console/challenge. The Bot Builder and the forum share this one session: GET /v1/session says who it
signs in, and Sign out is POST /v1/session/end, which ends it in all three.
The pages¶
| Page | What it shows and does | Explained in |
|---|---|---|
| Account | your organisation's name and plan, its members and their roles; invite by email, change a role, remove a member, close the organisation | this chapter |
| Keys | mint, rename, rotate and revoke keys; each key's grants; a minted key is shown once, here | below |
| Usage | each meter this month against its cap, by day; cache hits and the solve seconds they saved | chapter 16 |
| Billing | owners only: your plan, its price and currency, the card as Stripe describes it, the next charge, the invoices with their PDFs, any grace; subscribe, change interval or card, cancel | chapter 40 |
| Rules | the rule sheet, compiled on the page; nothing is saved | chapter 41 |
| Outcome phrasings | how each write's outcome is told to the user | chapter 42 |
| Reply rules | personal data by class, phrases never to say, the offers a reply may make, what must accompany a write or a citation | chapter 43 |
| Feedback | thumbs up and down of the last thirty days by what they were on; counts only | chapter 25 |
| Vocabulary | your vocabulary's versions and what each one's ledger says; reverting to the one before | chapter 25 |
| Miner | the hosted miner's runs, each applied or naming the check that held it back | chapter 25 |
| Grammar | the sentence shapes your users used that the selector could not read, and which have shipped | chapter 25 |
| Findings | the bug hunter's projects, scans and findings, and your decisions about them | chapter 28 |
| Jobs, Service, Storage | recent jobs as metadata; the queues; your stored artefacts, and any hold on one | chapters 9 and 16 |
| Settings | ir_only, feedback retention, the language the selector reads and your organisation's own identifiers; what an unreadable turn does, the answer composer and retrieval are each agent's own, in agent.yaml |
chapters 20 and 44 |
| Administrative history | owners only: every sign-in and every change, append-only | this chapter |
The console shows no solver content and no conversation. A policy, a certificate, a patch, a user's turn or an agent's reply never reaches a page; the feedback and accuracy pages are counts. The one exception is deliberate: a bug hunter finding is the product, so the Findings pages show it. Your agents' conversations, their tool calls and the documents they answer from stay on your own machine, so no page here could show them.
What you type is read before it is sent. The rule sheet, the outcome phrasings, the reply rules and a note on a finding are checked in your browser for e-mail addresses, telephone numbers, card numbers, IBANs, UK National Insurance numbers and Brazilian CPF numbers. A form with a match is not submitted, and the page names the kind and the field, never the value.
Every change is audited, with who made it, from where and when, and nothing changes on a link: every change is a form posted from the page.
Who may do what¶
| Owner | Admin | Viewer | |
|---|---|---|---|
| See every page | yes | yes | yes |
| Mint, rename, rotate and revoke keys | yes | yes | no |
| Settings, catalogue, rules, phrasings, reply rules, reverting the vocabulary | yes | yes | no |
Decide about a finding (with hunt_details) |
yes | yes | no |
| The administrative history | yes | no | no |
| Billing, members, renaming and closing the organisation | yes, signed in as a person | no | no |
A person's role comes from their membership. A session opened with a key is an admin, whoever minted the key: a key is a credential, not a person, so it never holds what only a person may do, which is the bill, the members and closing the organisation.
Keys¶
A key looks like this:
qls_live_7Kd3nQ9x R2mV… the prefix, an 8-character public id, then 43 characters of secret
qls_test_… the same shape, held to the fast profile
and is sent as Authorization: Bearer qls_live_…. The client reads it from QLS_API_KEY.
- A key is shown once, when it is minted, and never again by anyone, including us. We store only a one-way hash of it, so there is nothing to show. Keep it in your secret store, never in a file you commit.
- Live and test keys. A test key works like a live key held to the
fastprofile, and is refused on the forest queue: refused rather than quietly downgraded, because a downgraded request for a proof would answer with a verdict and no certificate. - What a key can do is set by your plan, and shown on the Keys page read-only. The console cannot
widen a key beyond its plan.
GET /v1/capabilitiesanswers the same question over the API. A key may be minted narrower than its plan, never wider. - Every authentication failure is the same failure: a missing header, a malformed key, an unknown or
revoked one, one past its rotation deadline. One
401, one message.
Your Stalwart key and your model's key¶
Two keys are easily confused, and neither ever stands in for the other:
| Your Stalwart key | Your model's key | |
|---|---|---|
| What it is for | everything you do with Stalwart: the client, the stalwart command, the API and the console |
calling your model's provider: Anthropic, OpenAI, Google or another |
| Where you get it | here, on the Keys page | your provider's own console |
| What it looks like | qls_live_… or qls_test_… |
whatever your provider issues |
| Where it is read from | QLS_API_KEY |
the provider's usual variable: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, … |
| What we keep of it | a one-way hash | nothing |
Your model's key is never entered in the console, and never sent to us with your agents' turns: your agent calls your model from your own machine (chapter 30). The one call that brings it to us is writing a guardrail, which carries it to the worker and deletes it as it is read (chapter 13).
The public id is neither. The Keys page lists each key by its public id, the 8 characters after the prefix, which tell your keys apart and cannot call the API. If the Keys page shows you only public ids, that is all it will ever show: the key itself was shown once, when it was minted. If it was not copied then, mint a new one, or rotate the old one.
Rotating¶
Rotating mints a replacement, links it to the old key, and keeps the old one working for a window you choose: at once, 24 hours, or 7 days. The default is 24 hours, because rotation that breaks production instantly is rotation nobody performs. At once is the answer to a leaked key, so that retiring a key on schedule and stopping a leak are the same action.
Revoking¶
Revoking stops a key within a minute everywhere, ends the console sessions it opened, and disconnects any stream it holds within 15 seconds. A member may always revoke their own session's key.
When a key leaks¶
Rotate it at once, from the Keys page: the leaked key stops within the minute, and its replacement is shown to you once. Then look at the key's last use on the Keys page, and at the Administrative history, for anything you did not do.
When every key is lost¶
Sign in as a person, with Google or an emailed link, and mint a new key on the Keys page. Only an
organisation that has also lost every member's sign-in, so that nobody can sign in at all, writes to
newaccounts@stalwart.it.
Pasting a key into the API reference¶
The API reference lets you try any operation with your own key. It is public and needs no key to read; a key is needed only to send a request. What the page does with your key:
- A request from the page is a real call: authenticated, rate-limited and metered against your key's quota like any other. It is never a sandbox or a test mode, and it is not free.
- The key goes to the host that served the page and nowhere else. The page's only server is its own origin, and its security policy lets it make requests to that origin only.
- The page keeps no key in your browser's storage, loads nothing from a third party, and sends no telemetry.
If you would rather not paste a production key, mint one for the purpose on the Keys page and revoke it afterwards (chapter 18).
The limits¶
- The console cannot widen a key beyond its plan, cannot show a key again, and shows no solver content.
- A key is a credential: a session opened with one can never manage billing or members.
- Revocation takes effect within a minute, not at the instant you click.