Search the docs⌘ K
  • Install Apps and find an appSilicon Apps · Start
  • Publish an appSilicon Apps · Start
  • Add sign-in to your appSilicon Accounts · Start
  • Get a Silicon accountSilicon Accounts · Start
  • Sign a Silicon into an appSilicon Accounts · Start
  • Verify a proofSilicon Accounts · Start
  • Receive webhooksSilicon Accounts · Start
  • Exchange, refresh, check and revoke tokensSilicon Accounts · Start
  • HTTP API referenceSilicon Accounts · Reference
  • ErrorsSilicon Accounts · Reference
  • silicon-accounts CLI referenceSilicon Accounts · Reference

Silicon Accounts docs

Add sign-in to your app, look after Carbon and Silicon accounts, and verify requests between apps. Start with the guide for your next step.

OverviewUpdated MarkdownEdit on GitHub
On this page

Silicon Accounts gives every Carbon (a person) and every Silicon (an agent) one personal account, and they carry that account into every app they sign in to.

If you are building an app, we do the sign-in for you. You choose the methods, the pages your users see and the details they share with you. We handle account creation, email and phone codes, Google and Apple, and your app's user list.

Some requests are public. For example, you can check whether an id is free without signing in:

Shell
export ACCOUNTS_URL=https://accounts.teamofsilicons.com   # or a local stack: http://localhost:8590
curl -s "$ACCOUNTS_URL/v1/ids/available?id=si:head_of_growth"
JSON
{"id": "si:head_of_growth", "available": true, "reason": null, "message": "si:head_of_growth is available.", "reclaimable": false, "suggestions": []}

The hosted service lives at accounts.teamofsilicons.com. For a local development stack, follow Run it yourself and set ACCOUNTS_URL=http://localhost:8590 instead.

You can reach us through the silicon-accounts CLI, the silicon-accounts-client Rust package or the HTTP API at $ACCOUNTS_URL/v1/. The CLI is built on that same Rust package.

Run silicon-accounts --help to see every command, or add --help to any command for its options. The CLI also carries guides you can read offline: silicon-accounts docs lists them, and silicon-accounts docs imports opens the import guide.

Start here

You are a Silicon.

  1. Get an account: create it yourself and name your custodian, or have your Carbon create it for you. You get an si:id and an STK, which is your password.
  2. Sign in to apps: you never see an app's sign-in page. You hand the app a short-lived token instead.
  3. Use the CLI, with the full command reference.

You are building an app.

  1. Add sign-in: send Carbons to the hosted pages, drop in the iframe or the snippet, or use any OpenID Connect library, then exchange the code for tokens.
  2. Configure sign-in: the methods and their order, redirect URIs, which details Carbons share with you (required or optional), your flows and who may sign in. The developer platform, developers.teamofsilicons.com, does all of it with live previews.
  3. Brand the pages so they look like your app.
  4. Import your existing users so nobody starts over.
  5. Verify tokens, receive webhooks about the accounts in your user base, and act at other apps with proofs.

You are a Carbon. Your account lives at accounts.teamofsilicons.com. There you see your details, your emails and phone numbers, the apps you signed in to (and what each one sees), the proofs apps issued on your behalf, and the Silicons you are custodian of. Being a custodian explains what you are responsible for, and Accounts explains what your account holds and what deleting it does.

How these docs are organised

  • Start pages are instructions. Each one begins with what you'll do and a working example, then walks through every step, every option and every error you can meet.
  • Learn pages explain why things work the way they do. Read them when you need to make a judgement call: the reasons are there so you can decide for yourself.
  • Reference pages list everything: the HTTP API, errors, limits, the Rust client and the CLI.

The words

wordmeaning
CarbonA person. Every person's account is a Carbon account.
SiliconAn agent. Its account is a Silicon account, with a password called an STK.
CustodianThe one Carbon responsible for a Silicon. Every Silicon always has exactly one.
AppAny application that signs its users in with Silicon Accounts. Apps are created in Silicon Apps, and their sign-in is set up on the developer platform, developers.teamofsilicons.com.
uuidThe permanent identifier of an account, like a8K. It never changes and is never reused.
c:id, si:idThe public, changeable id of a Carbon or a Silicon, like c:saket or si:head_of_growth.
MembershipAn account's relationship with an app: {app_id}:{uuid}, like briefcase:a8K.
STKA Silicon's password: stk- followed by hexadecimal digits.
Short-lived tokenWhat a Silicon (or a Carbon, from the CLI) hands an app to sign in to it: single use, 2 minutes.
User verification and App verification proofsTokens that let one app act at another, on behalf of a Carbon (User verification) or as itself (App verification).

Things to rely on

  • Store the uuid. Ids can change (the old one stays reserved for 10 days, then anyone may take it), but the uuid never does. We tell your app about id changes by webhook. uuids and ids explains why.
  • Errors say exactly what went wrong and why. Every error is {"error": {"code", "message", "hint"?, "details"?}}: a stable code to branch on, a message that names the problem, and usually a hint with the next step.
  • Keep the same key when you retry a change. Requests that create a Silicon, an import, a proof or a webhook secret, and requests that change a sign-in configuration, accept an Idempotency-Key header. Within the replay window, the same key and body give you back the original response. Removals can simply be repeated. Read the retry rules before you retry anything else.
  • Personal accounts only. Accounts are never shared and never belong to a group. A Carbon's account belongs to that Carbon and a Silicon's to that Silicon, and apps get only what the Carbon shares with them.

Numbers worth knowing (all of them are in limits):

whatvalue
Email and phone codes6 digits, valid 10 minutes; 10 per address per 10 minutes; 10 wrong in a row lock the address for 1 minute
Access token / refresh token30 minutes / up to 900 days
Short-lived token for an appsingle use, 2 minutes
Id changeold id reserved 10 days
Custodian request14 days to accept
Emails, phone numbersup to 10 each per Carbon
Importup to 100,000 rows or 50 MB per file

Run it yourself

A local stack is the whole service on your machine: Postgres, accounts-api, the account site, the developer platform (http://localhost:8600, where you sign in as one of an app's authors and set up its sign-in), mock Google and Apple, a mock email and SMS sender, and fake apps (briefcase, dm, remind, …) with fixed development secrets. No code reaches a real inbox or phone and no sign-in reaches the real Google or Apple, so it's also the safe place to try a change before you make it in production. From a checkout of the repository:

Shell
scripts/dev.sh --detach                     # builds, migrates, seeds and starts; prints every URL
export ACCOUNTS_URL=http://localhost:8590   # the account site; it forwards /v1/* and /.well-known/*
silicon-accounts id available si:head_of_growth     # the CLI reads ACCOUNTS_URL too (or pass --url)
scripts/stop.sh                             # stops the stack; Postgres keeps running (--db stops it)

It needs Rust 1.98, Node 24 or later with pnpm, and Postgres 16. If your Postgres isn't Homebrew's postgresql@16, set PG_BIN to the directory that holds its pg_ctl. The stack builds the CLI as target/debug/silicon-accounts, and Use the silicon-accounts CLI puts it on your PATH. Email and SMS codes go to the mock sender, so you read them from the development outbox: curl -s "$ACCOUNTS_URL/v1/dev/outbox?to=ada@example.test&limit=1" (service endpoints). scripts/dev.sh --help lists every option, including the ports and database for a second stack.

Where to find more

  • The account site: accounts.teamofsilicons.com, where a Carbon looks after their own account.
  • The developer platform: developers.teamofsilicons.com, where you set up everything about your app's sign-in: methods, Google and Apple, the details you ask for, flows and pages, redirect URLs, the user base and imports, webhooks and App verification proofs. The settings themselves are stored in Silicon Accounts.
  • Discovery for OpenID Connect libraries: https://accounts.teamofsilicons.com/.well-known/openid-configuration, with the keys at /.well-known/jwks.json.
  • The source of the service, the account site, the CLI, the Rust package and these docs: the silicon-accounts repository. Its public home, github.com/teamofsilicons/silicon-accounts, has the service, both sites, the client, the CLI and the documentation.
  • Found a bug? Run silicon-accounts report "what you ran, what you expected, what happened", with --pr <link> if you fixed it too (we'd be grateful).

Related

Silicon Accounts · Start · InstructionsAdd sign-in to your appSend your users to us to sign in, bring them back to your app, and exchange the code they return with for their tokens.Silicon Accounts · Start · InstructionsGet a Silicon accountCreate your own Silicon account and name your Carbon as its custodian, or let your Carbon create it for you. Save the STK the moment you see it, and wait for approval if you need to.Silicon Accounts · Learn · ExplanationAccountsWhat a Carbon or Silicon account holds, how you manage its emails and phone numbers, and what happens when it is deleted.Silicon Accounts · Reference · ReferenceHTTP API referenceFind any Accounts endpoint and who can call it, plus the rules every endpoint shares for errors, retries, pagination and limits.

Every page is plain Markdown at its address plus .md. Silicons can read llms.txt, llms-full.txt or the docs index, or call the MCP server.