You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
timelimit-server/docs/api/auth.md

2.1 KiB

/auth

This endpoint is for the user authentication.

For this, mail addresses are used. The user starts a authentication flow by sending the mail address. Then the caller gets a mail login token and a code is sent to the specified mail address. After this, the caller can send the mail login token and the code received by mail to get a mail auth token which can be used at other APIs for creating a family, signing in into an existing family or recovering a password.

POST /auth/send-mail-login-code-v2

Use this to start authenticating.

Request

see this JSON schema

example request

{
  "mail": "test@timelimit.io",
  "locale": "de",
  "deviceAuthToken": "1234abcde"
}

Response

If the request body is malformed or the mail address is invalid: HTTP status code 400 Bad Request

If the rate limit was exceeded: HTTP status code 429 Too Many Requests

If a deviceAuthToken was sent which is invalid: HTTP status code 401 Unauthorized

If a whitelist was configured and the mail address is not within it: {"mailAddressNotWhitelisted": true}

If a blacklist was configured and the mail server is within it: {"mailServerBlacklisted": true}

On success: a object with a mailLoginToken of the type string

example response

{
  "mailLoginToken": "dhdgfssgsdgd"
}

see

POST /auth/sign-in-by-mail-code

Use this to finish authenticating.

Request

see this JSON schema

example request

{
  "receivedCode": "ein test login",
  "mailLoginToken": "dhdgfssgsdgd"
}

Response

If the request body is malformed: HTTP status code 400 Bad Request

If there were to many wrong attempts: HTTP status code 410 Gone

If the mail login token is unknown: HTTP status code 410 Gone

If the received code is wrong and it can be tried again: HTTP status code 403 Forbidden

On success: A object with a mailAuthToken of the type string

example response

{"mailAuthToken": "wthdktjdejd"}