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'
Updated almost 2 years ago