REST API reference

All rest endpoints expects a JSON body and returns an JSON object.

Authentication

Set the Authorization header to the credential you provided when initializing your server.

Authorization: YOUR_CREDENTIAL

Faroe will return a 401 error response if the request has an invalid credential.

{
    "error": "NOT_AUTHENTICATED"
}

Responses

Successful responses will have a 200 status if it includes a response body or 204 status if not.

All error responses have a 4xx or 5xx status and includes a JSON object with an error field. See each endpoint's page for a list of possible response statuses and error codes.

{
    "error": "INVALID_DATA"
}

Data types

• Email address: Must be less than 256 characters long, have a "@", and a "." in the domain part. Cannot start or end with a whitespace.
• Password: Must be between 8 and 127 characters.

Models

• User
• User email verification request
• User TOTP credential
• Password reset request

Endpoints

Authentication

• POST /authenticate/password: Authenticate user with email and password.

Users

• POST /users: Create a new user.
• GET /users: Get a list of users.
• GET /users/[user_id]: Get a user.
• DELETE /users/[user_id]: Delete a user.
• POST /users/[user_id]/update-password: Update a user's password.

Email verification

• POST /users/[user_id]/email-verification-request: Create a new user email verification request.
• GET /users/[user_id]/email-verification-request: Get a user's email verification request.
• DELETE /users/[user_id]/email-verification-request: Delete a user's email verification request.
• POST /users/[user_id]/verify-email: Verify their email verification request code.

Email update

• POST /users/[user_id]/email-update-requests: Create a new user email update request.
• GET /users/[user_id]/email-update-requests: Gets a list of a user's email update requests.
• DELETE /users/[user_id]/email-update-requests: Deletes a user's email update requests.
• GET /email-update-requests/[request_id]: Get an email update request.
• DELETE /email-update-requests/[request_id]: Delete an email update request.
• POST /verify-new-email: Update a user's email by verifying their email update request code.

Two-factor authentication

• POST /users/[user_id/register-totp: Register a TOTP credential.
• GET /users/[user_id]/totp-credential: Get a user's TOTP credential.
• DELETE /users/[user_id]/totp-credential: Delete a user's TOTP credential.
• POST /users/[user_id]/verify-2fa/totp: Verify a user's TOTP code.
• POST /users/[user_id]/regenerate-recovery-code: Generate a new user recovery code.
• POST /users/[user_id]/reset-2fa: Reset a user's second factors with a recovery code.

Password reset

• POST /users/[user_id]/password-reset-requests: Create a new password reset request for a user.
• GET /password-reset-requests/[request_id]: Get a password reset request.
• DELETE /password-reset-requests/[request_id]: Delete a password reset request.
• POST /password-reset-requests/[request_id]/verify-email: Verify a reset request's email.
• POST /reset-password: Reset the user's password with a verified reset request.