Introduction

Authentication is based on a combination of an authentication token and a session token.
Authentication token can only be used to request a new session token while the session token is used for each operation in the API.
Both tokens can have an expiration time, ideally the session token should be short lived (e.g. 15 minutes) while the authentication token can have a longer lifespan (e.g. a year).
When the session token expires the client can request a new session token using the authentication token.
When the authentication token expires the user has to perform a new login process.

Step 1 – Get an authentication token (log in)

The client posts login data to the /tokens endpoint and receives an authentication token. The login can be either a single step process (e.g. username + password) or a two-step process, where the user needs to provide a secret such as in the case of a phone number + SMS code flow.

Single step login

Single step logins are used when the user does not need to provide additional data, such as when logging in with a combination of a username and password.

Request

curl --request POST \
     --url https://api.test.memento.zone/v1/tokens \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "device": {
          "make": "iPhone",
          "model": "iPhone6,2",
          "os_name": "iOS",
          "os_version": "14.0"
     },
     "identity": {
          "type": "username",
          "value": "my_username"
     },
     "authenticator": "password",
     "pin": "1234",
     "secret": "MyPa$$w0rd"
}
'

Response

{
  "created_at": "2022-10-24T14:23:58.045641Z",
  "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "error_code": "string",
  "error_message": "string",
  "expires_at": "2022-10-24T14:23:58.045641Z",
  "id": "bba3e889-75b6-4d88-a6a2-8ae461344b61",
  "status": "created",
  "token": "string",
  "updated_at": "2022-10-24T14:23:58.045641Z"
}

Two-step login

Two step logins are used when the user needs to provide a secret such as in the case of a phone number + SMS code.

Request (provide phone number)

curl --request POST \
     --url https://api.test.memento.zone/v1/tokens \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "device": {
          "make": "iPhone",
          "model": "iPhone6,2",
          "os_name": "iOS",
          "os_version": "14.0"
     },
     "identity": {
          "type": "phone",
          "value": "+44 123 1234 1234"
     },
     "authenticator": "sms",
     "pin": "1234"
}
'

Response

{
  "id": "5d3e070e-b41c-4e5c-901f-3af2b374d978",
  "created_at": "2022-11-11T14:43:10.894799613Z",
  "updated_at": "2022-11-11T14:43:10.894799722Z",
  "device_id": "7aa375d4-bfec-4530-8a65-fa723d7b9382",
  "status": "created",
  "expires_at": "2032-11-08T14:43:10.895374831Z"
}

Request (provide verification code)

curl --request POST \
     --url https://api.test.memento.zone/v1/tokens/id/secret \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "pin": "1234",
     "secret": "123456"
}
'

Response

{
  "created_at": "2022-10-24T14:23:58.045641Z",
  "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expires_at": "2022-10-24T14:23:58.045641Z",
  "id": "bba3e889-75b6-4d88-a6a2-8ae461344b61",
  "status": "created",
  "token": "C6Qz6RBrnnR2dECY6dgj6ibQAhuLa11cY3CevUZUQUHQULxuLk1kU2HjV2SDCb6l2cUQjHDKQpoAMqDh1npit3dMeGLWGBEolPenx3Ee2ATO5OSKWS6AXPyMI9wqypFHyB5fPOWRjnQ9rK2KBQQMouwMChsZgkBJXU49TuuU4SCwZSBiPu8XlPieWcV4GyYBmxjwQfPe9szxu85tlCFWdnPuM4VsbbuMaZsA6qXRw6rrqSI40jMsz6CkxZF7frxi",
  "updated_at": "2022-10-24T14:23:58.045641Z"
}

Step 2 – Get a session token

The client posts to the /sessions endpoint, sending the authentication token with the Authorization: Basic header. If the authentication token is active, a session token object is returned. If the server replies with a 401 Unauthorized the authentication token is either invalid or has expired. If the server replies with a 400 Bad Request the user account is invalid (e.g. has been locked).

Request

curl --request POST \
     --url https://api.test.memento.zone/v1/sessions \
     --header 'Authentication: Basic C6Qz6RBrnnR2dECY6dgj6ibQAhuLa11cY3CevUZUQUHQULxuLk1kU2HjV2SDCb6l2cUQjHDKQpoAMqDh1npit3dMeGLWGBEolPenx3Ee2ATO5OSKWS6AXPyMI9wqypFHyB5fPOWRjnQ9rK2KBQQMouwMChsZgkBJXU49TuuU4SCwZSBiPu8XlPieWcV4GyYBmxjwQfPe9szxu85tlCFWdnPuM4VsbbuMaZsA6qXRw6rrqSI40jMsz6CkxZF7frxi' \
     --header 'accept: application/json'

Response

{
  "created_at": "2022-10-24T14:23:58.045641Z",
  "expires_at": "string",
  "id": "bba3e889-75b6-4d88-a6a2-8ae461344b61",
  "token": "w5Yj8NUlwDemzRVmlk0JhcnrFL4ZNwcvnTBv7uLi1htEOganov1PdMqZhrBrCD3GozqGvXI3Yg57ukjP6if9j9sRMGYQYAFZraNnbKFSjUIqEpDiZXTamToAhyCAmQCsxGI18V1emZNhmAULSwfD9X6dGN8sUKNMIEHLekptH6hJpSMeIb8rvW48bBaBInsvdYdLXxlmbWY1s4nk6jVma1CjN7vYTdt1v6WZLoY6NYXE6lkaYoD2sfDLEpFtKOPd",
  "updated_at": "2022-10-24T14:23:58.045641Z"
}

Step – Using the session token

From this point on, the client will send the session token with the Authorization: Bearer header for each request to the endpoints. If the server replies with a 401 Unauthorized the session token is either invalid or has expired.

curl --request POST \
     --url https://api.test.memento.zone/v1/sessions/verify \
     --header 'Authorization: Bearer w5Yj8NUlwDemzRVmlk0JhcnrFL4ZNwcvnTBv7uLi1htEOganov1PdMqZhrBrCD3GozqGvXI3Yg57ukjP6if9j9sRMGYQYAFZraNnbKFSjUIqEpDiZXTamToAhyCAmQCsxGI18V1emZNhmAULSwfD9X6dGN8sUKNMIEHLekptH6hJpSMeIb8rvW48bBaBInsvdYdLXxlmbWY1s4nk6jVma1CjN7vYTdt1v6WZLoY6NYXE6lkaYoD2sfDLEpFtKOPd'