Skip to Content
Docs

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

FieldTypeAlways sent
environmentone of sandbox, productionYes
siteone of open, waitlistYes
userobject or nullYes
user.idstringYes
user.emailstring or nullYes
user.phonestring or nullYes
user.displayNamestringYes
user.rolesobjectYes
user.roles.participantbooleanYes
user.roles.advertiserIdstring or nullYes
user.roles.adminstring or nullYes
demoAccountslist of objectsYes
demoAccounts[].emailstringYes
demoAccounts[].labelstringYes
advertisersobjectYes
advertisers.byInvitationbooleanYes
emailobjectYes
email.simulatedbooleanYes
email.shownOnScreenbooleanYes
phoneobject or nullYes
phone.providerone of sandbox, identity_platformYes
phone.simulatedbooleanYes
phone.browserobject or nullYes
phone.browser.apiKeystringYes
phone.browser.projectIdstringYes
phone.browser.authDomainstringYes
signUpobject of one of participant, advertiser to object or nullYes
humanCheckobjectYes
humanCheck.providerstringYes
humanCheck.simulatedbooleanYes
humanCheck.siteKeystring or nullYes
humanCheck.tokenstring or nullYes
statusPagestring or nullYes

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

FieldTypeRequired
emailstring, at most 200 charactersYes

Answer

FieldTypeAlways sent
oktrueYes
minutesintegerYes
simulatedbooleanYes
sandboxCodestringNo

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

FieldTypeRequired
emailstring, at most 200 charactersYes
codestring, at most 12 charactersYes
displayNamestring, at most 80 charactersNo: empty if left out
asone of participant, advertiserNo: participant if left out

Answer

FieldTypeAlways sent
oktrueYes
createdbooleanYes

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

FieldTypeRequired
phonestring, at most 40 charactersYes

Answer

FieldTypeAlways sent
oktrueYes
phonestringYes
minutesintegerYes
simulatedtrueYes
sandboxCodestringYes

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

FieldTypeRequired
phonestring, at most 40 charactersNo
codestring, at most 12 charactersNo
idTokenstring, at most 4096 charactersNo
displayNamestring, at most 80 charactersNo: empty if left out
asone of participant, advertiserNo: participant if left out

Answer

FieldTypeAlways sent
oktrueYes
createdbooleanYes

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

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
phonestring, at most 40 charactersNo
codestring, at most 12 charactersNo
idTokenstring, at most 4096 charactersNo

Answer

FieldTypeAlways sent
changedbooleanYes

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

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
emailstring, at most 200 charactersYes

Answer

FieldTypeAlways sent
oktrueYes
minutesintegerYes
simulatedbooleanYes
sandboxCodestringNo

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

FieldTypeRequired
emailstring, at most 200 charactersYes
codestring, at most 12 charactersYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
namestringYes

Answer

FieldTypeAlways sent
oktrueYes
displayNamestringYes

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

FieldTypeAlways sent
oktrueYes
endedintegerYes

Refused with unauthorized, csrf.