Authentication

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'