Login and session management

Sign in, refresh tokens, sign out, and manage user sessions.

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

Hide properties

access_token · string

JWT Bearer token to include in subsequent requests. RS256-signed.

token_type · string

Always "Bearer".

expires_in · number

Seconds until the access token expires (for example, 86400 for 24 hours).

scope · string

Space-separated list of OAuth scopes granted to the token (for example, "email profile").

Examples

curl

curl --request POST \
  --url http://localhost:5000/v1/auth/signin \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]",
    "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

Status	Description
400 Bad Request	Request body is missing or malformed.
401 Unauthorized	Email 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

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

sign out current session

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

curl --request POST \
  --url http://localhost:5000/v1/auth/forgot-password \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]"
  }'

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

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

curl --request POST \
  --url http://localhost:5000/v1/auth/reset-password \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]",
    "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

curl --request GET \
  --url "http://localhost:5000/v1/auth/d8b9b81b-7232-4a7f-b9d3-4f7226129677/sessions" \
  --header "Authorization: Bearer <your-jwt-token>"

Status	Description
401 Unauthorized	No or invalid Bearer token.
403 Forbidden	The 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

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"
}

Status	Description
400 Bad Request	The session ID is not a valid UUID.
401 Unauthorized	No or invalid Bearer token.
403 Forbidden	The authenticated user does not own the session.