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¶
Sign up on the website's sign-up page, with Google or with an emailed link. No person at Stalwart is involved.
- 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.
Then the welcome page asks for your organisation's name and for you to accept the terms and the data-processing addendum; the versions you accepted are recorded. One step then opens a free account, makes you its owner, and mints its first live key, shown once, on that page. 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.
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 lasts twelve hours; 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 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 |
| Catalogue | your newest catalogue with its lints, reads and writes marked; its versions, and restoring one | chapter 21 |
| Rules | the rule sheet, compiled and linted on the page; saving it as a new catalogue version | 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 |
| Accuracy | the evaluation set written from your catalogue, scored, beside your users' thumbs | 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, what an unreadable turn does, the answer composer and retrieval |
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.
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.