OTP Verification

Request an OTP

Sends a one-time password to the specified email address.

POST /api/auth/request-otp

Authentication: None required

Rate-limited to 2 requests per hour per email address.

Request body

string

required

The email address to send the OTP to.

Response

success

boolean

required

true when the OTP was dispatched successfully.

message

string

required

Value: "OTP send successfully".

Error cases

Status	Message	Cause
`400`	Validation error message	Missing or invalid email
`403`	Service error message	Failed to generate or dispatch OTP
`429`	`"Too many requests."`	Rate limit of 2 per hour exceeded

Example

curl -X POST http://localhost:5000/api/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

{
  "success": true,
  "message": "OTP send successfully"
}

Verify an OTP

Verifies a one-time password for the given email address.

POST /api/auth/verify-otp

Authentication: None required

Rate-limited to 5 attempts per 15 minutes per email address.

Request body

string

required

The email address the OTP was sent to.

otp

string

required

The one-time password received by the user.

Response

success

boolean

required

true when the OTP is valid.

message

string

required

Value: "OTP verified successfully".

data

object

Additional verification result data returned by the OTP service.

Error cases

Status	Message	Cause
`400`	`"OTP verification failed"`	OTP is invalid or has expired
`429`	`"Too many requests."`	Rate limit of 5 attempts per 15 minutes exceeded

Example

curl -X POST http://localhost:5000/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "otp": "483920"
  }'

{
  "success": true,
  "message": "OTP verified successfully",
  "data": {}
}

Logout

Revokes the current session’s refresh token and clears the refreshToken cookie.

DELETE /api/auth/logout

Authentication: None required (uses the refreshToken cookie) If no cookie is present, the endpoint still returns a success response — the logout is treated as a no-op.

Response

success

boolean

required

Always true.

message

string

required

Value: "Logged out successfully".

Example

curl -X DELETE http://localhost:5000/api/auth/logout \
  -b cookies.txt

{
  "success": true,
  "message": "Logged out successfully"
}

Logout all devices

Revokes all active sessions for the authenticated user across all devices.

DELETE /api/auth/logout/all

Authentication: Required (Authorization: Bearer <access_token>)

Response

success

boolean

required

true when all sessions were revoked.

message

string

required

Value: "Logged out from all devices".

Error cases

Status	Message	Cause
`401`	`"Unauthorized"`	Missing or invalid access token
`500`	`"Logout failed"`	Unexpected server error

Example

curl -X DELETE http://localhost:5000/api/auth/logout/all \
  -H "Authorization: Bearer <access_token>" \
  -b cookies.txt

{
  "success": true,
  "message": "Logged out from all devices"
}

List active devices

Returns all active device sessions for the authenticated user. The current session is identified within the list.

GET /api/auth/devices

Authentication: Required (Authorization: Bearer <access_token>)

Response

success

boolean

required

true on success.

message

string

required

Value: "Devices fetched successfully".

data

object[]

Array of active device sessions. Each session object includes the token ID, device metadata, and creation timestamp.

Error cases

Status	Message	Cause
`401`	`"Unauthorized"`	Missing or invalid access token
`500`	`"Failed to fetch devices"`	Unexpected server error

Example

curl http://localhost:5000/api/auth/devices \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "message": "Devices fetched successfully",
  "data": [
    {
      "tokenId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "ip": "127.0.0.1",
      "createdAt": "2024-10-11T09:23:00.000Z",
      "isCurrent": true
    }
  ]
}

Logout a specific device

Revokes a specific device session by its token ID. Obtain the token ID from GET /api/auth/devices.

DELETE /api/auth/devices/:tokenId

Authentication: Required (Authorization: Bearer <access_token>)

Path parameter

tokenId

string

required

The UUID token ID of the session to revoke. Retrieve it from GET /api/auth/devices.

Response

success

boolean

required

true when the session was revoked.

message

string

required

Value: "Device logged out successfully".

Error cases

Status	Message	Cause
`401`	`"Unauthorized"`	Missing or invalid access token
`500`	`"Failed to logout device"`	Token ID not found or server error

Example

curl -X DELETE http://localhost:5000/api/auth/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "message": "Device logged out successfully"
}

Request password reset email

Sends a password reset link to the specified email address. For security, the response is always a success — no information is revealed about whether the email exists in the system.

POST /api/auth/send-reset-email

Authentication: None required

Request body

string

required

The email address associated with the account to reset.

Response

success

boolean

required

true when the request was processed.

message

string

required

Value: "Password reset email sent successfully".

Error cases

Status	Message	Cause
`400`	Validation error message	Missing or invalid email
`500`	`"Failed to send password reset email"`	Email dispatch error

Example

curl -X POST http://localhost:5000/api/auth/send-reset-email \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

{
  "success": true,
  "message": "Password reset email sent successfully"
}

Reset password

Resets the user’s password using the token from the password reset email.

POST /api/auth/reset-password

Authentication: None required

Request body

string

required

The email address of the account being reset.

token

string

required

The password reset token received in the reset email.

password

string

required

The new password to set for the account.

Response

success

boolean

required

true when the password was reset successfully.

message

string

required

Value: "Password has been reset successfully".

Error cases

Status	Message	Cause
`400`	Validation error message	Missing or invalid request fields
`500`	`"Failed to reset password"`	Token is invalid, expired, or server error

Example

curl -X POST http://localhost:5000/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "token": "reset-token-from-email",
    "password": "NewSecurePass456!"
  }'

{
  "success": true,
  "message": "Password has been reset successfully"
}

Overview

Auth

Posts

Analytics

Platforms

Payments

Profile

Admin

​Request an OTP

​Request body

​Response

​Error cases

​Example

​Verify an OTP

​Request body

​Response

​Error cases

​Example

​Logout

​Response

​Example

​Logout all devices

​Response

​Error cases

​Example

​List active devices

​Response

​Error cases

​Example

​Logout a specific device

​Path parameter

​Response

​Error cases

​Example

​Request password reset email

​Request body

​Response

​Error cases

​Example

​Reset password

​Request body

​Response

​Error cases

​Example

Build docs developers (and LLMs) love

Request an OTP

Request body

Response

Error cases

Example

Verify an OTP

Request body

Response

Error cases

Example

Logout

Response

Example

Logout all devices

Response

Error cases

Example

List active devices

Response

Error cases

Example

Logout a specific device

Path parameter

Response

Error cases

Example

Request password reset email

Request body

Response

Error cases

Example

Reset password

Request body

Response

Error cases

Example