Accounts, devices and keys
Partly builtOne Clay account, a key for each of your devices, and why Clay's own servers never hold a key that can act as you.
Clay has one account. You sign in to it once, and the editor, Phaistos and the command line all belong to it. What the account lets you do is split in two on purpose: being signed in (Clay’s services know it is you) and writing as you (your work in your own storage is signed with a key only your devices hold). This page explains both, and says plainly which parts exist today.
Today you can sign in with a passkey or with Google, manage the account on its own page, and pair a second device or an agent by hand with short codes. A new account is made together with its key. Making the pairing one click, recovering from a lost browser, and organisations are designed and not built.
One account, one page
The account page at id.withclay.org is where the account is managed: the ways you sign in, the browsers and devices that are signed in, the AI assistants you have connected, and a download of everything Clay holds about you. Phaistos and the editor sign you in to that same account; none of them is meant to have a login of its own.
Implemented Passkey and Google sign-in, the account page and its sections.
Implemented Phaistos has no sign-in or sign-up of its own. Its account panel sends you to the account page, which brings you back to where you were, and shows who is signed in. The page only returns you to Clay’s own addresses.
Clay stores a name and, if Google gave them, an email address and a photo. The sign-in itself is a passkey’s public key or Google’s identifier for you, never your email as a key. You can edit the name; the page has no way to delete an account yet.
Account and workspace identity
Your work lives in a workspace in storage you own (see the overview). A workspace belongs to an identity: an id, and behind it a key. The id is the first sixteen bytes of the SHA-256 hash of the identity’s first public key, so the id commits to the key and anyone can check that a key belongs to an id without asking a server.
Implemented Every editor and every command-line replica creates such a key the first time it runs. The editor keeps it as a non-extractable browser key, so scripts on the page can use it but cannot read it out; the command line keeps it in a file only you can read.
Implemented Every new account gets a key at the moment it is created. The account page makes it in your browser, as a non-extractable key like the editor’s, and the account’s id is the hash of that key, so “my account” and “my workspace” are one id whether you signed up with a passkey or with Google. A sign-up without a key is refused. The account page shows the identity and its public key, and warns when only one device holds the key.
Implemented Accounts made before this have a random id. They are linked once to an identity by a signed message from a page that holds a key, and changing that later needs a fresh sign-in and is recorded. Today the key that links must be the identity’s own first key; a later device’s key will be accepted once the service can read device statements.
Why each device has its own key
A device does not copy your key. It makes its own, and your identity signs a short public statement saying “this key is one of my devices”. The statement names the device, can be given an expiry, and can later be cancelled by another statement. Statements live in your bucket, are checked by whoever reads them, and need no server: from the statements alone a reader can decide, offline, whether a key may act as you.
Nothing secret is ever transferred between devices. A lost or stolen device is cancelled by one statement, and the other devices carry on with their own keys.
This also settles who must not hold a key. Whoever is the authority over an identity holds its key. For a personal account that is you, so Clay holds no key that could act as you. The identity service at id.withclay.org may carry public statements from one device to another, but it cannot create one: if someone broke into it, they could not write into anyone’s workspace as them. That is what “Clay never operates where your code lives” means for identity.
The keys are P-256 (the same curve a passkey uses), signatures are ECDSA, and the statements are a fixed binary layout that is rejected if anything in it is unknown, so that a reader cannot accept something wider than its signer meant. The full byte layout and the rules for deciding validity are written up in the design documents, which will be published with the source.
Signing in and writing as you
| Proves | Checked by | State | |
|---|---|---|---|
| Signed in | that a request comes from your account | Clay’s services, online | Implemented for browsers and for AI assistants; not yet for the command line |
| Writes as you | that this device’s key is one of your identity’s devices | anyone reading your storage, offline | Implemented by hand-paired devices and agents |
Signing in gets you into Clay’s services: the account page, Phaistos pages that are stored by Clay, and later Cloud and the registry. It does not let anyone write to your own storage. Writing as you needs a device statement. Keeping the two apart means the worst a stolen session cookie can do is what a session can do; it cannot rewrite your history.
Approving a new device
Implemented Pairing is manual. On the new device, clay device request (or “Join an existing identity” in the editor’s Settings) prints a join request signed by the new device’s own key, which proves it holds the key. On a device that can sign for your identity, clay device grant (or “Add a device”) checks the request and signs the statement. Two six-digit codes guard the exchange: one the new device shows and you compare before signing, and one shown after signing that the new device makes you type, so a substituted request is caught. The new device then verifies the statement against your identity, offline, and starts writing as you.
Pairing does not copy storage credentials. Each device is set up with the storage location itself.
Designed, in progress clay login is being built now. Its first part signs the command line in to your account through your browser, with a token that appears on the account page and can be revoked there. It does not yet make the device write as you. The second part replaces the codes with the account: the command line sends its join request when you sign in, a device that holds your key approves it (usually in the same browser, on the sign-in page, in one click), and the signed statement comes back to the command line, which verifies it itself and does not trust the service for it. Browsers you sign in to later work the same way: you are signed in at once, and writing as you waits until a device that holds a key approves the new browser.
Signing out
Implemented You can end any browser session, or all of them but this one, from the account page. A device’s statement is cancelled with clay device revoke, or from the editor’s Settings; a revoke is permanent, and re-adding a device needs a new statement.
Designed “Sign out” on the account page also ends writing as you for that device: it revokes the token and asks a device that holds your key to sign the revoke. Until one does, the row says so, rather than claiming bucket access has ended. A command line’s device statement lasts 90 days and is renewed quietly while it stays signed in, so even an unsigned revoke has a short limit.
If you lose a device
A browser can lose its key: the person clears site data, or the browser removes the data of a site it has not seen for a while. Any one surviving device that is allowed to approve others is enough to get back in, but a person with a single browser has nothing left, and the account page’s job is to make that case hard to reach.
Designed, not built A personal account must have a recovery method before it can write as you. You can sign in without one, and the account page then says why writing is off and offers to set one up. It can be either of two:
- A passkey. Your authenticator keeps it, not the browser’s storage, and it is often synced between your devices. When you add a passkey, a device you hold signs a statement making the passkey’s key an approver of new devices. On a fresh browser you sign in with the passkey, the browser makes a new key, and the passkey approves it. No second device is needed.
- A recovery code. The account page makes a separate recovery key in your browser and a random 128-bit code, shown to you once in groups of four characters with a check character so typos are caught. The code is turned into an encryption key with HKDF, which needs no slow password hashing because the code is random rather than chosen by a person, and that key seals the recovery key with AES-256-GCM. The sealed blob is stored both with your account and in your bucket, so recovery works even if Clay’s service is unavailable. It is useless without the code, and the code never goes to Clay: you keep it in a password manager or on paper. Using it approves the new browser and then replaces the recovery key and code with fresh ones, so a code that has been typed in once counts as spent.
Both exist so that a locked-down computer where passkeys are disabled can still recover. The recovery key is the only key in the system that can be exported, because it has to be backed up, and before recovery ships, the account page will refuse inline scripts and any code other than its own and Google’s sign-in, so there is little for an attacker to inject.
If you have no passkey, no code and no surviving device, writing as you means a new identity. Clay cannot restore the old one for a personal account, because it never held the key, and the page tells you so rather than hiding it.
Agents
Implemented An agent, such as a bot or a coding assistant, has its own id and key, never yours. clay agent request on the agent makes a join request; you run clay agent grant (or “Add an agent” in the editor), which signs an agent statement that expires, by default after 30 days and never after more than a year. Your workspace then shows the agent’s branches read-only, under its own id, and you merge what you accept; with the default setting the agent can also read yours. An agent can issue no statements of its own, and you can revoke one with clay agent revoke.
Designed clay login --agent will do the token half too, so an agent signs in to your account (listed under AI assistants, ending after 30 days without renewal) and receives its statement in one step.
AI assistants you connect to Clay through the account page already work in a different, simpler way: they get a revocable token, listed there, and no key.
Organisations
Designed, not built Organisations do not exist in Clay yet. The design follows the same rule: the organisation is the authority over its members’ work identities, so the organisation holds the key, in its own key service or, if it chooses, one that Clay runs for it.
- Sign-in issues short certificates. After you sign in through your organisation’s own identity provider (Google Workspace, Okta or Entra over OpenID Connect), the organisation signs a statement for your device that lasts one to thirty days. Recovery is signing in again; offboarding is disabling the person in the identity provider, because the certificates run out, and the organisation can revoke them sooner. Members hold no recovery key.
- Two membership policies. The organisation chooses. Personal identities allowed suits a start-up: you keep your own identity and key, and the organisation certifies that you are a member; leaving ends the membership, not your identity. Managed identities only suits a large enterprise: the organisation issues you a separate work identity, and you keep your personal one for personal work.
- Work moves in by copy. A personal identity never turns into an organisation’s, and the organisation never takes over your key, because that would hand it your personal history and your other memberships. Definitions keep their hashes, names are pointed again in the organisation’s storage, and the history stays signed by the personal key that wrote it.
What is built
| Part | State |
|---|---|
| Passkey and Google sign-in, the account page | Implemented |
| A key and identity id for each editor and command-line replica | Implemented |
Device and agent statements, offline verification, revocation, pairing with codes (clay device, clay agent, editor Settings) |
Implemented |
| Signed branch heads, so other devices refuse a forged one | Implemented |
| Account and workspace identity are one id (a key at sign-up; older accounts linked once) | Implemented |
clay login (command line signed in to the account) |
Designed, in progress |
| Approving a device from the account, one click | Designed |
| Recovery by passkey or code; one required to write as you | Designed |
| Organisations, SSO certificates, membership policies | Designed |
The detailed design documents are not public yet; they will be published with the source.