Confirm
471
edits
Changes
add API summary and typical client flows
ceb52ce8e80c632c 5591f3c3e1667685
76590dba8d924713 78eb6e2197fed99f
= Keyserver Protocol Summary =
* POST /account/create (email,srpV,srpSalt) -> ok (server sends verification email)
** creates a user account
* POST /session/auth/start (email) -> loginSrpToken,SRP stuff
* POST /session/auth/finish (loginSrpToken,SRP stuff,deviceInfo) -> keyFetchToken, sessionToken
* GET /session/status [authed] () -> ok, or error
* POST /session/destroy [authed] () -> ok
** for detaching a device, destroy all tokens
* POST /certificate/sign [authed] (pubkey) -> cert
** only if primary recovery method verified
* GET /account/recovery_methods [authed] () -> list of recovery methods with verified status
** does not require verified-recovery-method
** use "Accept: text/event-stream" header for server-sent-events; server will send "update" event with the new content of the resource any time it changes.
* POST /account/recovery_methods/send_code [authed] (recovery_method) -> ok
* POST /account/recovery_methods/verify_code (code) -> ok
** this code will come from a clickable link and is an unauthenticated endpoint
** this could maybe take the recovery method if that would be helpful
** sets verified flag on recovery method
* GET /account/keys [authed with keyFetchToken] () -> kA/wrap(kB)
** single-use, only if primary recovery method is verified, encrypted results
* GET /account/devices [authed] () -> list of devices
* POST /password/change/auth/start [authed] () -> changePasswordSrpToken, SRP stuff
** requires that the email associated with the session is verified
* POST /password/change/auth/finish [authed] (changePasswordSrpToken, SRP stuff) -> keyFetchToken, accountResetToken
* POST /password/forgot/send_code (recovery method) -> forgotPasswordToken
** sends code to recovery method (email for now, maybe SMS later)
** this is a short code, not a clickable link
* POST /password/forgot/verify_code (forgotPasswordToken, code) -> accountResetToken
** sets verified flag on recovery method
* POST /account/reset [authed+encrypted by accountResetToken] (wrap(kB),srpV,srpSalt) -> ok
** single-use, does not require a verified recovery method, revoke all tokens for account, send notification email to user
* POST /get_random_bytes
== Typical Client Flows ==
Create account
* POST /account/create (email,srpV,srpSalt) -> ok (server sends verification email)
* POST /session/auth/start (email) -> loginSrpToken,SRP stuff
* POST /session/auth/finish (loginSrpToken,SRP stuff,deviceInfo) -> keyFetchToken, sessionToken
* GET /account/recovery_methods [authed] () -> list of recovery methods with verified status
** (optional, only if user requests resend) POST /account/recovery_methods/send_code [authed] (recovery_method) -> ok
** POST /account/recovery_methods/verify_code (code) -> ok
* GET /account/keys [authed with keyFetchToken] () -> kA/wrap(kB)
* POST /certificate/sign [authed] (pubkey) -> cert
Attach to new device
* POST /session/auth/start (email) -> loginSrpToken,SRP stuff
* POST /session/auth/finish (loginSrpToken,SRP stuff,deviceInfo) -> keyFetchToken, sessionToken
* GET /account/keys [authed with keyFetchToken] () -> kA/wrap(kB)
** (if unverified-error, do waitUntilEmailVerified, then try again)
* POST /certificate/sign [authed] (pubkey) -> cert
Forgot password
* POST /password/forgot/send_code (recovery method) -> forgotPasswordToken
* POST /password/forgot/verify_code (forgotPasswordToken, code) -> accountResetToken
* POST /account/reset [authed+encrypted by accountResetToken] (wrap(kB),srpV,srpSalt) -> ok
* GOTO "Attach to new device"
Change Password
* start in logged-in state
* POST /password/change/auth/start [authed] () -> changePasswordSrpToken, SRP stuff
* POST /password/change/auth/finish [authed] (changePasswordSrpToken, SRP stuff) -> keyFetchToken, accountResetToken
* GET /account/keys [authed with keyFetchToken] () -> kA/wrap(kB)
* POST /account/reset [authed+encrypted by accountResetToken] (wrap(kB),srpV,srpSalt) -> ok
* GOTO "Attach to new device"
