# Part 0 · The way in

One door for every product, at `id`. You type one thing (your phone number, an e-mail or a username) and press
**Continue**; the page reads what it is from its shape and asks for the next step. It never says whether an account
exists: a number or address with no account gets the same next page as one with an account, and nothing is sent to it.

## 0.1 Signing in with your phone

**Who** · Anyone whose account holds a verified phone number.

**Where** · **Sign in**.

**Before you start** · The phone, able to receive a text.

**The steps**
1. Type your number, as you'd dial it (`024 411 1148`) or in full (`+233 24 411 1148`), and press **Continue**.
2. **Enter the code**: type the six digits from the text, and press **Sign in**. Your phone may fill it in for you.
3. If the account has an authenticator set up, **Enter your code** follows (1.1). If it hasn't signed in for a while
   and has a password, **Your password, too** follows (0.5).

**What the record shows** · `sign_in_code`: one row per code asked for, the code itself never kept. The sign-in log:
`login`. Nuntius's message log: the text, with the code blanked.

**Who is told** · You, by the text.

**What can go wrong**
- *No text.* The number may have no account yet; the page doesn't say. **Send again** is offered after 30 seconds,
  then 60, then 2 minutes.
- *"That code isn't right. You have 3 more tries."* Each code takes five tries, then a new one is needed.
- *"That code has run out."* A code lasts 10 minutes, and only the newest one works.
- *"Let's pause for a bit."* See 0.4.
- *"That number can't be read."* Give it with its area code, or in full with `+`.

## 0.2 Signing in with an e-mail or a username

**Who** · Anyone whose account holds a verified e-mail, or a username (often one an organisation set up for someone with no phone or e-mail).

**Where** · **Sign in**.

**Before you start** · Your password.

**The steps**
1. Type your e-mail or username and press **Continue**.
2. **Signing in as …**: type your password and press **Sign in**. **change** goes back to the first step.
3. With an authenticator set up, **Enter your code** follows (1.1).

**What the record shows** · The sign-in log: `login`, or `login_failed` with what was typed.

**Who is told** · Nobody.

**What can go wrong**
- *"That password doesn't match an account by that name."* It never says which half was wrong. Wrong passwords in a
  row lock the account (1.6), whichever phone, e-mail or username was typed.
- *A username has no "Forgot your password?".* The school office resets it, until the account adds a phone or e-mail of
  its own.

## 0.3 An e-mail code instead of the password

**Who** · Anyone signing in with an e-mail.

**Where** · **Signing in as …** › **E-mail me a code instead**.

**Before you start** · Access to that mailbox.

**The steps**
1. Press **E-mail me a code instead**.
2. **Check your e-mail**: type the six digits and press **Sign in**. **Use your password instead** goes back.

**What the record shows** · `sign_in_code`, and the e-mail log: `sign_in.code`, with the code blanked.

**Who is told** · You, at the address you typed, even one your account keeps private.

**What can go wrong**
- *Nothing arrives.* Check spam; the address may have no account. The same waits and limits apply as for texts.

## 0.4 When it pauses

**Who** · Anyone, on a number or address that has had too many codes.

**Where** · **Let's pause for a bit**, instead of the code.

**Before you start** · Nothing.

**The steps**
1. Wait until the time shown, or press **Sign in another way** and use your password, or another phone, e-mail or
   username your account has.

**What the record shows** · `sign_in_pause`, by the number's hash: the wrong codes counted, and how long it's paused.

**Who is told** · Nobody.

**What can go wrong**
- *Why it paused.* Ten wrong codes within an hour, across however many codes, pause the number for an hour, then two,
  then four, while the last pause was within a day. More than five codes an hour or ten a day to one number, ten an
  hour from one network address, or three to other numbers in the same range within 10 minutes also pause it: that is
  what SMS-pumping fraud looks like.
- *"One more step: let the check below finish."* A second code from the same network address within the hour asks the
  browser to prove it's a person: Cloudflare Turnstile, with a puzzle the browser solves itself behind it (**Bot
  check**).

## 0.5 When it asks a little more

**Who** · An account with a password that hasn't signed in for 90 days (**Quiet after**), or ever, signing in with a code.

**Where** · **Your password, too**, after the code.

**Before you start** · Your password.

**The steps**
1. Type your password and press **Continue**.

**What the record shows** · The sign-in log: `login`, or `login_failed` (it counts towards the lock).

**Who is told** · Nobody.

**What can go wrong**
- *An account with no password* signs in with the code alone: it has nothing else to give.
- *The authenticator is always asked* after a code as after a password, whenever it's set up.

## 0.6 Signing in to a product

**Who** · Anyone opening a product (Campus, Loop, Books, Desk) that signs people in through `id`.

**Where** · The product's **Sign in**, which brings you to `id`, then back.

**Before you start** · Nothing: if you're already signed in at `id`, you go straight back.

**The steps**
1. Sign in at `id` as in 0.1 to 0.3, if you aren't already.
2. You're back in the product, signed in. Another product, even on another address, signs you in the same way without
   asking again.
3. If the product needs more for the page you're opening, **:product asks for your password** shows: type it and press
   **Confirm**, and you go straight back.

**What the record shows** · The sign-in log: `login` once, at `id`; `password_confirmed` if a product asked for more.
Passport's tokens for that product (`oauth_access_token`).

**Who is told** · Nobody. When you sign out, at `id` or in a product, every product that session signed into is told and
signs you out too.

**What can go wrong**
- *"This account has no password yet."* The product needs one for that page; add a password to your account first.
- *The product sends you somewhere that isn't its own address.* `id` refuses before you sign in: it only returns people
  to the addresses of that product's live organisations.

## 0.7 Joining with a new organisation

**Who** · Anyone starting a product for an organisation, while the platform keeps self-registration open (`sign_up.open`).

**Where** · A product's **Start free**, which opens `id` with that product named; or `id`'s **/join**, which asks which
product to start with.

**Before you start** · A mobile or an e-mail, and the organisation's region and district.

**The steps**
1. **Create your account**: your name and your phone or e-mail; press **Continue** and type the code sent to it. A number
   that already has an account signs in to it instead, and the name typed is set aside.
2. **Tell us about your school** (or organisation): its name; its short name, the initials until you type one, which opens
   the product at `{product}/{short}` and `{short}.{product}`; the country; the region and district. What kind of
   organisation it is follows from the product, and is asked only if the product serves more than one kind.
3. **Start …**: the product on its Free plan. You're its owner.
4. **Open …** takes you to the product at its new address, which signs you in through `id`.

**What the record shows** · The organisation (with its kind, region and district), your membership as its owner, the
product's Free plan and its address (`instance`), and `workspace.created` in its audit log. The product hears by webhook
(`entitlement.granted`) and makes its own side.

**Who is told** · You, by the code. The product, by webhook.

**What can go wrong**
- *"Another organisation has that short name on …"* Try another; the same short name may be free on another product.
- *"That district isn't in the region chosen."* Choose the region first; the districts follow it.
- *"We're not sending codes to new numbers just now."* The platform's brake is on (by hand, or because codes jumped);
  use an e-mail, or try later. Numbers that already sign in are never held.

## 0.8 Your account at id

**Who** · Anyone with an account.

**Where** · **Home**, **How you sign in** and **Devices**, under **You** in the menu.

**Before you start** · Nothing.

**The steps**
1. **Home** shows your organisations, each with its products: press one to open it. With none yet, it says what happens
   when an organisation adds you.
2. **How you sign in**: **Add a number or e-mail**, type the code sent to it, and it signs you in too. A second one is kept
   to you until you share it. **Choose one** sets a username for good; **Set a password** works soon after signing in.
3. **Devices**: each browser you're signed in on; sign one out, or **Sign out everywhere**, which signs you out of every
   product too.
4. If an organisation set up your account for you, **Make it mine** proves a phone or e-mail of yours. If that number
   already has an account, you're asked once, and the two become one, with nothing lost.

**What the record shows** · The sign-in log: `device_signed_out`, `signed_out_everywhere`, `account_claimed`. The audit
log: `account.made`, `account.merged`.

**Who is told** · Products, by webhook, when you sign out everywhere (`account.signed_out`) or an account is folded into
yours (`account.merged`).

**What can go wrong**
- *"This is already on another account."* One number signs one account in. If that account is yours, claim or sign in with
  it.
- *"This is your last way to sign in."* Add another first.

## 0.9 Passkeys, Google and Microsoft

**Who** · Anyone with an account; Google and Microsoft once the platform has their keys.

**Where** · **Sign in** › **Use a passkey** or **Continue with …**; **How you sign in** › **Passkeys** › **Add one**, and
**Google** or **Microsoft** › **Link**.

**Before you start** · For a passkey, a phone or computer that can make one, and a sign-in within the last 15 minutes.

**The steps**
1. **Add one** under Passkeys: your device asks for your face, fingerprint or PIN, and it's added.
2. Next time, **Use a passkey** on the sign-in page: no code to wait for.
3. **Link** Google or Microsoft from How you sign in. Google also links itself the first time you **Continue with Google**
   with an address it has verified that's already on your account; Microsoft signs you in only once you've linked it,
   since its addresses aren't always verified.

**What the record shows** · The sign-in log: `login`. A passkey is more than a code, so a product asking for more is
satisfied by it.

**Who is told** · Nobody.

**What can go wrong**
- *"No account has that … address yet."* Google and Microsoft never make an account: sign in another way, then link it.
- *"… didn't say that address is verified."* Sign in another way, then link it from How you sign in.
- *"That … account is already linked to another account."* One identity signs one account in.
