Auth API
#
POST /authRegisters a new user
api | string | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
created | string | Integer timestamp representing the date the client generated the account's encryption keys. Example "1622494310383" |
string | The account email. | |
ephemeral | boolean | Whether the initial session created for this account is ephemeral ("Stay signed in" unchecked). |
identifier | string | Should equal the account email. |
origination | string | Should equal "registration" |
password | string | The server password generated by the client from the user's master password. |
pw_nonce | string | The nonce generated by the client for the user's encryption key. |
version | string | The protocol version the client used to generate the user's encryption key. Latest is "004". |
#
Response#
POST /auth/sign_inAuthenticates a user and returns a session.
api | string | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
string | The account email. | |
ephemeral | boolean | Whether the session created for this account is ephemeral ("Stay signed in" unchecked). |
password | string | The server password generated by the client from the user's master password. |
#
Response#
GET /auth/paramsQueries the parameters used for key generation for an email address. Queried before signing into an account.
api | string | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
string | The account email. |
#
Response#
POST /auth/change_pwChanges a user's password.
api | string | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
created | string | Integer timestamp representing the date the client generated the account's new encryption keys. Example "1622494310383" |
identifier | string | The account email. |
origination | string | Should equal "password-change" |
current_password | string | The old server password generated by the client from the user's master password. |
new_password | string | The new server password generated by the client from the user's master password. |
pw_nonce | string | The nonce generated by the client for the user's encryption key. |
version | string | The protocol version the client used to generate the user's encryption key. Latest is "004". |
#
Response#
Sessions#
Session ModelField | Type | Description |
---|---|---|
uuid | string | Unique identifier of the session |
user_uuid | string | Unique identifier of the user |
user_agent | string | The user agent used to create the session |
api_version | string | The server API version used to create the session |
access_token | string | The access token used to authenticate requests |
refresh_token | string | The refresh token used to extend tokens |
access_expiration | datetime | The expiration time of the access token |
refresh_expiration | datetime | The expiration time of the refresh token |
created_at | datetime | Date and time of creation of the session |
updated_at | datetime | Last updated date and time of the session |
- Each
session
includes the API version they were created with. This way we can deny sessions for a given API version if we detect a vulnerability with that version in the future - Sessions are created in the following cases:
- When a user signs in
- When a user registers a new account
#
Authenticated requestsThe Authorization
request header field is used by clients to make authenticated request. Bearer
is the only authentication scheme allowed.
The client must send the access
token generated by the session, in the Authorization
header. For example:
Below is a list of endpoints related to session management:
Method | URL | Params | Description | Successful response code |
---|---|---|---|---|
POST | /auth/sign_out | None | Terminates the current session | 204 |
DELETE | /session | uuid | Terminates the specified session by UUID | 204 |
DELETE | /sessions | None | Terminates all sessions, except the current one | 204 |
GET | /sessions | None | Lists all sessions active sessions | 200 |
POST | /session/token/refresh | refresh_token | Obtains new pair of access_token and refresh_token | 200 |
A successful request to GET /sessions
returns the following JSON response:
#
Obtaining tokensTokens can be obtained every time the user performs any of the following actions:
- When a user signs in
- When a user registers an account
- When the tokens are refreshed
#
Refreshing tokensWhen an expired access_token
is provided in the Authorization
HTTP header, the following JSON response is returned:
HTTP Status Code: 498 Expired Access Token
To continue accessing resources, the access_token
must be refreshed. That is, the current access_token
is replaced with a new one with an extended expiration date.
To refresh an access_token
, a valid refresh_token
is needed. This refresh_token
must meet the following requirements:
- It should belong to the session of the
access_token
- It should not be expired
Since the refresh_token
is of single-use, a new refresh_token
is obtained when the access_token
is refreshed.
Refreshing tokens is a process that is transparent to the user, meaning that the client will perform the requests to keep valid tokens without user intervention.
Here's how to refresh tokens:
Send a
POST
request to/session/token/refresh
. The body should contain a JSON paylaod with therefresh_token
:The
refresh_token
is validated on the server. Depending of the circumstances, there should be two outcomes:The provided
refresh_token
is valid. If so, a new pair of tokens is generated and the following JSON response is returned:The provided
refresh_token
is expired. If so, the following JSON response is returned:HTTP Status Code:
400 Bad Request
User must start a new session by re-entering their credentials.
#
Expiration#
SessionsSessions should be terminated after a period of inactivity. This is for best security practices.
Long-lived sessions
are a good choice for our use case, because it can build a better user experience than expiring sessions for a short idle-timeout.
- A
session
that remains inactive for1 year
will be terminated, along with alltokens
#
TokensName | Type | Expiration |
---|---|---|
access | Short-lived | 60 days |
refresh | Long-lived | 1 year |
- A
refresh
token is of single-use, while anaccess
token can be used as long as it is not expired