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.
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.
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.