# Accounts and sign-in

Signing in with a code sent to an email address or a phone, the session it starts, and the account behind every experience.

Source: https://reachagents.com/docs/api/accounts

## Signing in
Signing in by email takes two calls: `POST /api/auth/code` emails a code to the address, and `POST /api/auth/verify` trades the code for a session. The session is the cookie `aa_session`, sent with every call after. There are no passwords.

```sh
curl https://reachagents.com/api/auth/code -H "x-reachagents-client: web" -H "content-type: application/json" -d '{"email":"you@example.com"}'
curl https://reachagents.com/api/auth/verify -c cookies.txt -H "x-reachagents-client: web" -H "content-type: application/json" -d '{"email":"you@example.com","code":"123456"}'
```

Signing in by phone is `POST /api/auth/phone/verify`, with the proof that the person holds the number. Where Google verifies numbers, the browser does that with Google's own library and sends the ID token Google gives it; with the simulated provider, `POST /api/auth/phone/code` makes the code first.

A person with an agent starts an account with their phone number, and a business with an email address (`signUp` in `GET /api/session` says which ways are open). An account signs in either way it has, and adds the other on its profile. One account can be a participant, an advertiser, or both.

## Read who is signed in
`GET /api/session`

No sign-in.

The account the session cookie belongs to, if any, with its roles and its email address and phone number, and what the screens need before anyone signs in: whether this is the sandbox, whether advertisers join by invitation, whether email and the human check are simulated, how a phone number is verified here (`phone`: the simulation, or Google in the browser, with the public settings its library needs) and which ways each audience may start an account (`signUp`).

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `environment` | one of `sandbox`, `production` | Yes |
| `site` | one of `open`, `waitlist` | Yes |
| `user` | object or null | Yes |
| `user.id` | string | Yes |
| `user.email` | string or null | Yes |
| `user.phone` | string or null | Yes |
| `user.displayName` | string | Yes |
| `user.roles` | object | Yes |
| `user.roles.participant` | boolean | Yes |
| `user.roles.advertiserId` | string or null | Yes |
| `user.roles.admin` | string or null | Yes |
| `demoAccounts` | list of objects | Yes |
| `demoAccounts[].email` | string | Yes |
| `demoAccounts[].label` | string | Yes |
| `advertisers` | object | Yes |
| `advertisers.byInvitation` | boolean | Yes |
| `email` | object | Yes |
| `email.simulated` | boolean | Yes |
| `email.shownOnScreen` | boolean | Yes |
| `phone` | object or null | Yes |
| `phone.provider` | one of `sandbox`, `identity_platform` | Yes |
| `phone.simulated` | boolean | Yes |
| `phone.browser` | object or null | Yes |
| `phone.browser.apiKey` | string | Yes |
| `phone.browser.projectId` | string | Yes |
| `phone.browser.authDomain` | string | Yes |
| `signUp` | object of one of `participant`, `advertiser` to object or null | Yes |
| `humanCheck` | object | Yes |
| `humanCheck.provider` | string | Yes |
| `humanCheck.simulated` | boolean | Yes |
| `humanCheck.siteKey` | string or null | Yes |
| `humanCheck.token` | string or null | Yes |
| `statusPage` | string or null | Yes |

## Email a sign-in code
`POST /api/auth/code`

No sign-in. Send `x-reachagents-client: web`.

Step one of signing in. The answer is the same whether or not the address has an account. Only a simulated email provider that shows codes on screen answers with the code, as `sandboxCode`.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `email` | string, at most 200 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `minutes` | integer | Yes |
| `simulated` | boolean | Yes |
| `sandboxCode` | string | No |

**Refused with** `rate_limited`, `invalid_email`, `too_many_codes`, `email_not_sent`, `invalid_input`, `csrf`.

## Sign in with the code
`POST /api/auth/verify`

No sign-in. Send `x-reachagents-client: web`.

Step two: the code typed back. It sets the session cookie. An address with no account gets one where its audience (`as`) may start one by email: a business may, and a person with an agent starts with a phone number instead (`sign_up_by_phone`). An address the deployment names as an owner may always start one, whatever `as` says, and becomes an owner.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `email` | string, at most 200 characters | Yes |
| `code` | string, at most 12 characters | Yes |
| `displayName` | string, at most 80 characters | No: empty if left out |
| `as` | one of `participant`, `advertiser` | No: `participant` if left out |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `created` | boolean | Yes |

**Refused with** `rate_limited`, `invalid_email`, `unauthorized`, `email_taken`, `sign_up_by_phone`, `invalid_input`, `csrf`.

## Make a sign-in code for a phone number, where texts are simulated
`POST /api/auth/phone/code`

No sign-in. Send `x-reachagents-client: web`.

Only with the simulated provider, which texts nothing and answers with the code as `sandboxCode`. Where Google verifies numbers, the browser does it with Google’s own library and sends the ID token Google gives it to `/api/auth/phone/verify`.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `phone` | string, at most 40 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `phone` | string | Yes |
| `minutes` | integer | Yes |
| `simulated` | `true` | Yes |
| `sandboxCode` | string | Yes |

**Refused with** `rate_limited`, `invalid_phone`, `phone_off`, `phone_in_browser`, `too_many_codes`, `invalid_input`, `csrf`.

## Sign in with a phone number
`POST /api/auth/phone/verify`

No sign-in. Send `x-reachagents-client: web`.

The proof that the person holds the number: the simulated code typed back, or Google’s ID token (`idToken`). It sets the session cookie. A number on no account starts one where its audience (`as`) may start one by phone, which a person with an agent does

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `phone` | string, at most 40 characters | No |
| `code` | string, at most 12 characters | No |
| `idToken` | string, at most 4096 characters | No |
| `displayName` | string, at most 80 characters | No: empty if left out |
| `as` | one of `participant`, `advertiser` | No: `participant` if left out |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `created` | boolean | Yes |

**Refused with** `rate_limited`, `invalid_phone`, `phone_off`, `token_required`, `code_required`, `unauthorized`, `phone_unchecked`, `proof_spent`, `proof_too_old`, `proof_used`, `fictional_number`, `simulated_phone`, `phone_taken`, `phone_recently_moved`, `sign_up_by_email`, `invalid_input`, `csrf`.

## Sign out of this browser
`POST /api/auth/sign-out`

No sign-in. Send `x-reachagents-client: web`.

Ends the session the cookie belongs to, if any, and clears the cookie.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `csrf`.

## Read the account and what is held about it
`GET /api/account`

Signed in: the session cookie.

Everything the profile screen shows, in one answer, for the roles the account has: its email address, its phone number and when it was verified, its name, which experiences it has, and for a participant or an advertiser what is held about them.

**Answer:** a JSON object.

**Refused with** `unauthorized`.

## Add or change the account’s phone number
`POST /api/account/phone`

Signed in: the session cookie. Send `x-reachagents-client: web`.

With the proof that the person holds it, as signing in by phone takes it: the simulated code, or Google’s ID token. A number belongs to one account, and one taken off another account recently cannot be added yet.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `phone` | string, at most 40 characters | No |
| `code` | string, at most 12 characters | No |
| `idToken` | string, at most 4096 characters | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `changed` | boolean | Yes |

**Refused with** `rate_limited`, `invalid_phone`, `phone_off`, `token_required`, `code_required`, `unauthorized`, `phone_unchecked`, `proof_spent`, `proof_too_old`, `proof_used`, `fictional_number`, `simulated_phone`, `phone_taken`, `phone_recently_moved`, `invalid_input`, `csrf`.

## Take the phone number off the account
`DELETE /api/account/phone`

Signed in: the session cookie. Send `x-reachagents-client: web`.

Refused while the number is the account’s only way in: an email address is added first.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `no_phone`, `only_way_in`, `unauthorized`, `csrf`.

## Email a code to an address the account will add
`POST /api/account/email/code`

Signed in: the session cookie. Send `x-reachagents-client: web`.

For an account started with a phone number. Only a simulated email provider that shows codes on screen answers with the code, as `sandboxCode`.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `email` | string, at most 200 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `minutes` | integer | Yes |
| `simulated` | boolean | Yes |
| `sandboxCode` | string | No |

**Refused with** `rate_limited`, `invalid_email`, `too_many_codes`, `email_not_sent`, `invalid_input`, `unauthorized`, `csrf`.

## Add an email address to the account, with its code
`POST /api/account/email`

Signed in: the session cookie. Send `x-reachagents-client: web`.

Receipts and notices go to it, and the account can sign in with it too.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `email` | string, at most 200 characters | Yes |
| `code` | string, at most 12 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `rate_limited`, `invalid_email`, `unauthorized`, `has_email`, `email_taken`, `invalid_input`, `csrf`.

## Change the name a person is greeted by
`PUT /api/account/name`

Signed in: the session cookie. Send `x-reachagents-client: web`.

Tidied to one line first. A name that is already the one kept changes nothing.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `displayName` | string | Yes |

**Refused with** `name_required`, `name_too_long`, `invalid_input`, `unauthorized`, `csrf`.

## Sign out of every browser
`POST /api/account/sign-out-everywhere`

Signed in: the session cookie. Send `x-reachagents-client: web`.

Ends every session of this account, the one asking included. A connected agent is not a session and stays connected.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `ended` | integer | Yes |

**Refused with** `unauthorized`, `csrf`.
