Auth
Introduction
This page outlines a comprehensive user authentication system, including registration, biometrics, password reset, and verification processes. The system emphasizes security, particularly in the context of biometric authentication and verification procedures. For testing, please insert "https://sandbox-staging-app.berify.io" into the {domain}section of the URL.
Sign up
POST /auth/sign-up/{provider}
Creates user data with the received information, which includes email, phone, firstName, lastName and password. The account created will be in an unverified state, which limits the usability of most features. Currently, the provider options are limited to only email and password.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request parameters:
- provider: string (Default value : email-password)
Request body:
- email: string
- phone: string
- firstName: string
- lastName: string
- password: string
Example:
- URL
- Body
https://{domain}/api/auth/sign-up/email-password
{
"email": "test@gmail.com",
"phone": "+1-582***743",
"firstName": "Myles",
"lastName": "Drake",
"password": "Aa********"
}
Response:
- user:
- email: string
- phone: string
- firstName: string
- lastName: string
- error: string
- HTTP 200
- HTTP 400
{
"user": {
"email": "test@gamil.com",
"phone": "+1-582***743",
"firstName": "Kevin",
"lastName": "Chen"
}
}
{
"error": "Field(s) cannot be empty." | "user already created." | "Password requires at least 8 characters." | "Password requires at least one uppercase and one lowercase letter." | "Password must be in ASCII characters." | "Password requires at least one number."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Create biometrics
POST /auth/biometrics
A public key will be submitted when called, and it will check if the account uses third-party login. If not, the public key will be saved to the database. When the biometricsKey column has a value, it indicates that biometric authentication is activated.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request body:
- publicKey: string
- id: string
- signature: string
Example:
- URL
- Body
https://{domain}/api/auth/biometrics
{
"publicKey": "test@gmail.com",
"id": "989f86c0-5f87-4017-97d4-4ec318b7dee8",
"signature": "Myles"
}
Response:
- id: string
- error: string
- HTTP 200
- HTTP 400
{
"id": "c738ef3b-a882-40ef-a7e8-0474178f6631"
}
{
"error": "Field(s) cannot be empty." | "id not found." | "Email not verified." | "Biometrics setting does not match this phone." | "Biometrics signature error."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Forget password
POST /auth/forgetPassword/{provider}
Called when a user forgets their password and requests a password reset. A token will be recorded in the database, and an email or SMS will then be sent for resetting the password,depending on the contact method chosen. The email or SMS expires in 3 minutes.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request parameters:
- provider: string (Default value : email-password)
Request body:
- identifier: string
Example:
- URL
- Body
https://{domain}/api/auth/forgetPassword/email-password
{
"identifier": "test@gmail.com"
}
Response:
- expires: Date
- error: string
- HTTP 200
- HTTP 400
{
"expires": "2024-03-14T09:58:56.145Z"
}
{
"error": "Field(s) cannot be empty." | "User not found."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Reset password
POST /auth/resetPassword/{provider}
Checks whether the reset password email or SMS is still valid (not expired). If the email or SMS is expired, the user will need to request the forget-password API to resend a new one. If the token exists, it indicates a forget password workflow (which can be initiated without logging in), and the API will check if the corresponding record exists in the database. If the record is found, the user can proceed to reset their password. If the token does not exist, it indicates a reset password workflow, which can only be initiated when the user is logged in. Currently, the provider options are limited to email and password.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request parameters:
- provider: string (Default value: email-password)
Request body:
- tokenId: string
- password: string
Example :
- URL
- Body
https://{domain}/api/auth/resetPassword/email-password
{
"tokenId": "77a64841-eb9c-4e27-aee3-33d2c7ccf5a0",
"password": "Aa********"
}
Response:
- id: string
- error: string
- HTTP 200
- HTTP 400
{
"id": "c738ef3b-a882-40ef-a7e8-0474178f6631"
}
{
"error": "Field(s) cannot be empty." | "token not found." | "User not found." | "Request has expired." | "Password requires at least 8 characters." | "Password requires at least one uppercase and one lowercase letter." | "Password must be in ASCII characters." | "Password requires at least one number."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Send verify
POST /auth/sendVerify/{provider}
Sends a time-sensitive verification SMS when an account is logged in, which expires in three minutes. Currently, the provider options are limited to only email and password.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request parameters:
- provider: string (Default value: email-password)
Request body:
- identifier: string
Example:
- URL
- Body
https://{domain}/api/auth/sendVerify/email-password
{
"identifier": "test@gmail.com"
}
Response:
- expires: Date
- identifier: string;
- token: string;
- error: string
- HTTP 200
- HTTP 400
{
"expires": "2024-03-14T10:10:25.282Z",
"identifier":"example@gamil.com",
"token":"hus9mmntdmfah7botnsaxswh0a1vca8xvjj2cg1djriwf7hee2kucd4xhfp25g5r"
}
{
"error": "Field(s) cannot be empty." | "User not found."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Check verify
POST /auth/verify/check
Checks if the email is verified.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request body:
- identifier: string
Example:
- URL
- Body
https://{domain}/api/auth/verify/check
{
"identifier": "test@gmail.com"
}
Response:
- verify: boolean
- error: string
- HTTP 200
- HTTP 400
{
"verify": true
}
{
"error": "Field(s) cannot be empty."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.
Verify
POST /auth/verify/{provider}
Checks if the verification SMS is still valid. If it is, this API will update the verification time in the database, thus completing the authentication. If not, a resend of the verification SMS will be needed. Currently, the provider options are limited to email and password only.
Request header:
- secretKey: string. Use "App-Berify-Secret".
- secret: string
Request parameters:
- provider: string (Default value: email-password)
Request body:
- identifier: string (User email)
- token: string (Send verify api response token)
Example:
- URL
- Body
https://{domain}/api/auth/verify/email-password
{
"identifier": "example@gmail.com",
"token": "hus9mmntdmfah7botnsaxswh0a1vca8xvjj2cg1djriwf7hee2kucd4xhfp25g5r"
}
Response:
- id: string
- error: string
- HTTP 200
- HTTP 400
{
"id": "c3aa965e-f3ac-433b-8c38-29f311326e21"
}
{
"error": "Field(s) cannot be empty." | "verificationToken not found." | "identifier does not match." | "User not found."
}
HTTP status code summary:
200(OK) - Everything worked as expected.401(Unauthorized) - Invalid or missing access token.405(Method Not Allowed) - Unacceptable HTTP method for requested resource.