Skip to main content

​
Sign in

POST /auth/signin Authenticates a registered user and returns a JWT access token together with a refresh token.

​
Request body

​
email
string
required
The user’s email address. Must be a valid email format. Leading and trailing whitespace is stripped automatically.
​
password
string
required
The user’s password.

​
Response

​
statusCode
number
HTTP status code. 200 on success.
​
message
string
Human-readable result message.
​
data
object

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/signin \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com",
    "password": "S3cureP@ss!"
  }'
200 response
{
  "statusCode": 200,
  "message": "User logged in successfully",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "email profile"
  }
}

​
Error responses

StatusDescription
400 Bad RequestRequest body is missing or malformed.
401 UnauthorizedEmail or password is incorrect, or the email is not verified.

​
Refresh token

POST /auth/refresh-token Generates a new access token using a valid refresh token. Use this endpoint when the current access token has expired.

​
Request body

​
refreshToken
string
required
The refresh token received at sign-in.

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/refresh-token \
  --header "Content-Type: application/json" \
  --data '{
    "refreshToken": "<your-refresh-token>"
  }'
200 response
{
  "statusCode": 200,
  "message": "Token refreshed successfully",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "email profile"
  }
}

​
Sign out

POST /auth/signout Invalidates the current session. Requires a valid Bearer token.
This endpoint requires the Authorization: Bearer <token> header.

​
Request body

​
sessions
string[]
Optional list of specific session IDs to invalidate. When omitted, the current session is invalidated.

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/signout \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{}'
200 response
{
  "statusCode": 200,
  "message": "User logged out successfully"
}

​
Forgot password

POST /auth/forgot-password Sends a password-reset link to the user’s email address.

​
Request body

​
email
string
required
Email address of the account for which to initiate a password reset.
​
brandLogoUrl
string
Optional URL of a brand logo to include in the reset email. Must include a protocol and a valid TLD (for example, https://example.com/logo.png).
​
platformName
string
Optional display name of the platform, used in the reset email body.
​
endpoint
string
Optional base URL the reset link should point back to (for example, https://app.example.com).
​
clientAlias
string
Optional client alias to scope the reset link to a specific front-end client (for example, "VERIFIER").

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/forgot-password \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com"
  }'
200 response
{
  "statusCode": 200,
  "message": "Password reset link sent"
}

​
Reset password (token-based)

POST /auth/password-reset/:email Completes the password-reset flow by setting a new password using the token delivered by email.

​
Path parameters

​
email
string
required
The email address of the account whose password is being reset.

​
Request body

​
password
string
required
The new password to set for the account.
​
token
string
required
The verification token received in the password-reset email.

​
Examples

curl --request POST \
  --url "http://localhost:5000/v1/auth/password-reset/alice%40example.com" \
  --header "Content-Type: application/json" \
  --data '{
    "password": "N3wS3cureP@ss!",
    "token": "abc123verificationtoken"
  }'
200 response
{
  "statusCode": 200,
  "message": "Password reset successfully"
}

​
Reset password (authenticated)

POST /auth/reset-password Allows a signed-in user to change their password by providing their current password.

​
Request body

​
email
string
required
The user’s email address.
​
oldPassword
string
required
The user’s current password.
​
newPassword
string
required
The new password. Must be different from oldPassword.

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/reset-password \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com",
    "oldPassword": "S3cureP@ss!",
    "newPassword": "N3wS3cureP@ss!"
  }'
200 response
{
  "statusCode": 200,
  "message": "Password reset successfully"
}

​
Get all sessions

GET /auth/:userId/sessions Returns all active sessions for the specified user. Requires a valid Bearer token. Users may only retrieve their own sessions.
This endpoint requires the Authorization: Bearer <token> header.

​
Path parameters

​
userId
string
required
UUID of the user whose sessions to retrieve. Must match the authenticated user’s ID.

​
Examples

curl --request GET \
  --url "http://localhost:5000/v1/auth/d8b9b81b-7232-4a7f-b9d3-4f7226129677/sessions" \
  --header "Authorization: Bearer <your-jwt-token>"
StatusDescription
401 UnauthorizedNo or invalid Bearer token.
403 ForbiddenThe authenticated user is trying to access another user’s sessions.

​
Delete a session

DELETE /auth/:sessionId/sessions Deletes a specific session by its ID. Requires a valid Bearer token.
This endpoint requires the Authorization: Bearer <token> header.

​
Path parameters

​
sessionId
string
required
UUID of the session record to delete.

​
Examples

curl --request DELETE \
  --url "http://localhost:5000/v1/auth/3f2e1d4c-0000-0000-0000-000000000001/sessions" \
  --header "Authorization: Bearer <your-jwt-token>"
200 response
{
  "statusCode": 200,
  "message": "Session deleted successfully"
}
StatusDescription
400 Bad RequestThe session ID is not a valid UUID.
401 UnauthorizedNo or invalid Bearer token.
403 ForbiddenThe authenticated user does not own the session.

Build docs developers (and LLMs) love

Get started for freeTalk to us