API docs by Redocly

API for Password, Passkey, Magic Link, and OIDC Authentication (1.0.0)

Download OpenAPI specification:

Marinescu Alexandru: amarinescu.dev@gmail.com License: Apache License 2.0

API for user registration and authentication using multiple methods: username/password with capability of 2fa, passkey (WebAuthn), magic link, and OIDC providers (Google, GitHub, etc.).

Password Authentication Module

Register a new user

This endpoint allows a new user to create an account using their email and password. After registration, the user must verify their email to complete the registration process successfully.

Request Body schema: application/json
required

Request body for user registration.

name
required
string [ 1 .. 64 ] characters

The user's full name

email
required
string <email> [ 1 .. 64 ] characters
password
required
string >= 8 characters ^(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_\-+=\[\]...

Must start with a capital letter and contain at least one special character

confirmPassword
required
string >= 8 characters ^(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_\-+=\[\]...

Must match the password field

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "john.doe@example.com",
  • "password": "Password@123",
  • "confirmPassword": "Password@123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 201,
  • "message": "Registration successful. A verification email has been sent to your email address.",
  • "data": {
    },
  • "metadata": {
    }
}

Authenticate a user with email and password

This endpoint allows an existing user to log in using their email and password. Upon successful authentication, an access token (and optionally a refresh token) is returned. If the user has two-factor authentication enabled, additional steps may be required to complete the login process.

Request Body schema: application/json
required

Credentials for user login

email
required
string <email> [ 1 .. 64 ] characters
password
required
string >= 8 characters ^(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_\-+=\[\]...

Must start with a capital letter and contain at least one special character

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@example.com",
  • "password": "Password@123"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication pending, your email address has not yet been verified. Please confirm your email to proceed.",
  • "data": {
    },
  • "metadata": {
    }
}

Request a password reset for a user account

Initiates the password reset process for a user by submitting their email address. If the user has two-factor authentication (MFA) enabled, an MFA verification step will be required before sending the password reset instructions. Otherwise, a password reset email will be sent directly.

Request Body schema: application/json
required

Email address of the user requesting a password reset

email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@gmail.com"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Two-factor authentication required. Please enter your verification code to complete this process.",
  • "data": {
    },
  • "metadata": {
    }
}

Complete the password reset process

Completes the password reset process for a user account using a valid verification code. The request must include the verification code (typically received via email) and the new password. Upon successful verification, the user's password is updated, existing authentication cookies are cleared, and the user is advised to log in again. If the password reset was not initiated by the user, they are encouraged to contact support immediately. The operation also records contextual information such as IP address and user agent for security auditing purposes.

Request Body schema: application/json
required

Password reset request payload including verification code and new password

verificationCode
required
string [ 1 .. 64 ] characters
password
required
string >= 8 characters ^(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_\-+=\[\]...

Must start with a capital letter and contain at least one special character

Responses

Request samples

Content type
application/json
{
  • "verificationCode": "8ee6af17747140d8951121739",
  • "password": "Password@123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Password reset completed. If you didn’t request this change, please contact support immediately.",
  • "data": {
    },
  • "metadata": {
    }
}

Refresh the user's access token using a valid refresh token

Issues a new access token (and optionally a new refresh token) for an authenticated session. The request must include a valid refresh token stored in the user's HTTP-only cookie. If the refresh token is valid and the session is still active, a new access token will be returned and authentication cookies will be updated. If the refresh token is expired, invalid, or mismatched, the session will be invalidated and all authentication cookies will be cleared to enforce re-authentication. This endpoint ensures seamless session continuity while maintaining security best practices.

Authorizations:
RefreshTokenCokie

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Access token successfully refreshed. Your session remains active.",
  • "data": {
    },
  • "metadata": {
    }
}

Log out the authenticated user and invalidate the current session

Terminates the current authenticated session by invalidating all active authentication tokens and clearing related cookies (accessToken, refreshToken). This ensures that both the access token and any linked refresh token can no longer be used. The endpoint is typically called when a user explicitly logs out or when a session needs to be forcefully closed for security reasons. Requires a valid access token cookie for authentication and session validation. After a successful logout, the client should remove any cached session state and redirect the user to a login page.

Authorizations:
AccessTokenCokie

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Logout successful, you have been securely signed out.",
  • "data": {
    },
  • "metadata": {
    }
}

Resend verification email

Sends a new verification email to a registered user who has not yet verified their email address. This endpoint is typically used when a user requests to receive another confirmation link after registration.

Request Body schema: application/json
required

Verify a user's email address

email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@gmail.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Verification code was resended to email, please check your inbox!",
  • "data": {
    },
  • "metadata": {
    }
}

Check if email is available

Checks whether a given email address is already registered in the system. This endpoint is typically used during the registration process to prevent duplicate accounts.

Request Body schema: application/json
required

Verify a user's email address

email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@gmail.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Email does not exists in our database. Please register a new account !",
  • "data": {
    },
  • "metadata": {
    }
}

Authenticate a user with email and password

Verifies a user's email address using a verification token sent via email. Upon successful verification, the user's account is marked as confirmed, allowing them to complete the login process or other protected actions.

Request Body schema: application/json
required

Verify a user's email address

code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "n3910310n013912310sa"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Email address successfully verified. You can now proceed to login.",
  • "data": {
    },
  • "metadata": {
    }
}

Mfa Module

Retrieve temporary TOTP secret and QR code for MFA setup

Initiates the setup process for Multi-Factor Authentication (MFA) using TOTP (Time-Based One-Time Password). Returns a temporary secret key and a QR code that the user can scan in their authenticator app (e.g., Google Authenticator, Authy). The temporary secret must be verified by the user to finalize MFA enrollment. This endpoint requires the user to be authenticated via a valid access token cookie.

Authorizations:
AccessTokenCokie

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "We've sent a magic link to your email. Click it to successfully finish your registration process.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify the MFA code for a user

Verifies the multi-factor authentication (MFA) code provided by the user. This step is required after MFA setup or during a login flow to validate the one-time code generated by the authenticator app or sent via email/SMS. Upon successful verification, the MFA setup is confirmed or the login session is allowed.

Authorizations:
AccessTokenCokie
Request Body schema: application/json
required

Contains the one-time verification code generated by the user's authenticator app (e.g., Google Authenticator, Authy, Microsoft Authenticator) or received via email/SMS. The code must be exactly 6 digits and valid for the current authentication window.

code
required
string

The 6-digit one-time password (OTP) generated by the user's authenticator app or received via the selected MFA method.

Responses

Request samples

Content type
application/json
{
  • "code": "482913"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "MFA setup completed successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Disable (revoke) Two-Factor Authentication (2FA) for the current user

Revokes (disables) Two-Factor Authentication (2FA) for the authenticated user. The user must provide a valid MFA verification code generated by their authenticator app. Once verified, the user's 2FA secret and backup codes will be permanently removed.

Authorizations:
AccessTokenCokie
Request Body schema: application/json
required

Contains the one-time MFA code generated by the user's authenticator app. This code is used to verify ownership of the 2FA secret before disabling it.

code
required
string

The 6-digit one-time password (OTP) generated by the user's authenticator app. Must be valid at the time of request.

Responses

Request samples

Content type
application/json
{
  • "code": "481293"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Two-factor authentication has been successfully disabled for your account.",
  • "data": {
    },
  • "metadata": {
    }
}

Disable Two-Factor Authentication (2FA) using a backup code

Disables Multi-Factor Authentication (2FA) for the currently authenticated user using one of their previously generated backup codes. This endpoint can be used when the user no longer has access to their authenticator app but still possesses a valid backup code. Upon successful verification of the provided backup code, all remaining backup codes are invalidated, the MFA secret is removed, and 2FA is fully disabled for the account.

Authorizations:
AccessTokenCokie
Request Body schema: application/json
required

A JSON object containing the backup code the user wishes to use for disabling MFA. The code must be one of the valid, unused backup codes generated when MFA was enabled.

backupCode
required
string

The valid unused backup code associated with the user's account.

Responses

Request samples

Content type
application/json
{
  • "backupCode": "3F9A2B7QK"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Two-factor authentication has been successfully disabled for your account.",
  • "data": {
    },
  • "metadata": {
    }
}

Log in using a backup code

Authenticates a user by consuming one of their valid MFA backup codes. This endpoint is typically used when a user cannot access their authenticator app but has saved backup codes. Upon successful verification, a new authenticated session is created, access and refresh tokens are issued, and the used backup code is invalidated (removed from the account). The mfaToken cookie used during the MFA flow is cleared upon successful login.

Authorizations:
MfaTokenCokie
Request Body schema: application/json
required

The valid unused backup code associated with the user's account. The backup code must match one of the stored valid codes and will be invalidated once used.

backupCode
required
string

The valid unused backup code associated with the user's account.

Responses

Request samples

Content type
application/json
{
  • "backupCode": "3F9A2B7QK"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication successful, you have been signed in successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify MFA code during login

Validates the one-time MFA code provided by the user during the login process. This endpoint finalizes the multi-factor authentication (MFA) login flow by verifying the 6-digit time-based one-time password (TOTP) generated by the user’s authenticator app. Upon successful verification, a new authenticated session is created, and both access and refresh tokens are issued. The temporary mfaToken cookie is cleared once login is complete.

Authorizations:
MfaTokenCokie
Request Body schema: application/json
required

Contains the one-time MFA code generated by the user's authenticator app.

code
required
string

The 6-digit one-time password (OTP) generated by the user's authenticator app. Must be valid at the time of request.

Responses

Request samples

Content type
application/json
{
  • "code": "481293"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication successful, you have been signed in successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify MFA code for password reset

Verifies the one-time MFA code submitted by the user in order to proceed with a password reset. Upon successful verification, a password reset email is sent to the user's registered email address with a link to complete the password change process. This endpoint also clears the temporary MFA token cookie to prevent reuse.

Authorizations:
MfaTokenCokie
Request Body schema: application/json
required

Contains the one-time MFA code generated by the user's authenticator app.

code
required
string

The 6-digit one-time password (OTP) generated by the user's authenticator app. Must be valid at the time of request.

Responses

Request samples

Content type
application/json
{
  • "code": "481293"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Password reset request successfully processed. Please check your email for further instructions.",
  • "data": {
    },
  • "metadata": {
    }
}

Passkey Authentication Module

Initialize a passkey registration session

Starts the registration process for a new user using passwordless passkey authentication. The client provides the user's name and email address. If the email is not already registered, the server generates a PublicKeyCredentialCreationOptions object required by the WebAuthn API. This object includes a challenge, relying party information, user details, allowed algorithms, and authenticator selection criteria. It must be sent back to the client to complete the registration on the authenticator (device or platform). The server also stores a temporary PasskeyChallengeSession to track the challenge for later verification.

Request Body schema: application/json
required

Contains the user's registration information: - name: Full name or display name of the user. - email: User's email address for account identification.

name
required
string

The display name of the user registering a passkey.

email
required
string

The email address of the user registering a passkey.

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "john.doe@gmail.com"
}

Response samples

Content type
application/json
{
  • "statusCode": 201,
  • "success": true,
  • "message": "Passkey registration session has been successfully created.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify a passkey registration session and complete user signup

Verifies a passkey registration session provided by the client to complete the user signup process. The client must provide a PasskeyRegistrationResponse object containing the credential information generated during the passkey registration initiation.

Request Body schema: application/json
required

Contains the client-generated passkey registration response used to verify and complete the user signup.

id
required
string

Base64Url-encoded credential ID generated by the authenticator.

rawId
required
string

Raw Base64Url-encoded credential ID.

type
required
string
Value: "public-key"

Must always be "public-key".

required
object
authenticatorAttachment
string
Enum: "cross-platform" "platform"

Optional attachment modality of the authenticator.

object

Optional results of any WebAuthn client extensions.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "rawId": "string",
  • "type": "public-key",
  • "response": {
    },
  • "authenticatorAttachment": "cross-platform",
  • "clientExtensionResults": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 201,
  • "message": "Registration successful. A verification email has been sent to your email address.",
  • "data": {
    },
  • "metadata": {
    }
}

Initialize a passkey authentication (sign-in) session

Initializes a new WebAuthn passkey authentication session for a user who wants to sign in using a registered passkey. The endpoint generates a new WebAuthn authentication challenge and returns a set of PublicKeyCredentialRequestOptions that the frontend must pass to the browser's WebAuthn API (navigator.credentials.get).
The generated challenge is stored securely in the backend and will later be verified during the /passkey/authenticate/verify step. No user identifier is required at this stage, as the passkey authenticator handles user identification during the authentication process. This endpoint should be called from the frontend before invoking the browser WebAuthn API. --- Typical flow: 1. Frontend calls POST /passkey/authenticate/init 2. Backend generates and stores challenge + session 3. Frontend receives publicKeyCredentialRequestOptions 4. Frontend calls navigator.credentials.get(options) with those options 5. The result is sent to /passkey/authenticate/verify for final verification

Responses

Response samples

Content type
application/json
{
  • "statusCode": 201,
  • "success": true,
  • "message": "Passkey authentication session has been successfully created.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify a passkey authentication response and complete user login

Completes the passkey-based sign-in process by verifying the WebAuthn authentication response returned by the browser after calling navigator.credentials.get().

This endpoint:

  • Validates the cryptographic response (challenge, signature, authenticator data)
  • Ensures the passkey session is still valid and not consumed
  • Confirms that the user exists and is eligible for login
  • Creates a new authenticated session and issues secure access and refresh tokens

On success, the user is authenticated, tokens are issued, and authentication cookies are set.
If the user's email has not yet been verified, the endpoint returns a pending verification response instead of logging in.

Request Body schema: application/json
required

WebAuthn authentication response returned by the browser’s navigator.credentials.get() call.
It includes the credential ID, authenticator data, and digital signature required for verification.

id
required
string

The base64url-encoded credential ID uniquely identifying the passkey credential.

rawId
required
string

The raw credential ID in base64url format. Usually identical to id but encoded differently.

type
required
string
Value: "public-key"

The credential type. For WebAuthn, always "public-key".

authenticatorAttachment
string
Enum: "cross-platform" "platform"

Indicates the attachment modality of the authenticator:

  • "platform": built into the device (e.g. Touch ID, Windows Hello)
  • "cross-platform": external authenticator (e.g. security key)
object

Results from any WebAuthn extensions used during authentication.

required
object

Contains the raw cryptographic materials returned by the authenticator, required for verifying the authentication response.

Responses

Request samples

Content type
application/json
{
  • "id": "hT1lYyBBtU4QxZ5L5RjYuw",
  • "rawId": "hT1lYyBBtU4QxZ5L5RjYuw",
  • "type": "public-key",
  • "authenticatorAttachment": "platform",
  • "clientExtensionResults": {
    },
  • "response": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication pending, your email address has not yet been verified. Please confirm your email to proceed.",
  • "data": {
    },
  • "metadata": {
    }
}

Initialize a new passkey registration session for an authenticated user

Initializes a WebAuthn passkey registration session that allows a logged-in user to securely add a new passkey to their account.

This endpoint performs the following steps:

  1. Validates the authenticated user and checks that they match the {userid} path parameter.
  2. Retrieves existing passkeys associated with the account to prevent re-registration of the same authenticator.
  3. Generates a new WebAuthn PublicKeyCredentialCreationOptions object (challenge, relying party info, user identity, supported algorithms, etc.).
  4. Persists the challenge session in the database with the "add-new-key" purpose for later verification.

The client (frontend) should use the returned publicKeyOpts object as input for the navigator.credentials.create() call in the browser.

This route requires a valid access token cookie for authentication.

Authorizations:
AccessTokenCokie
path Parameters
userid
required
string
Example: 64f2d2ab8e2e1b03b6f3cd44

The unique identifier of the user who is adding a new passkey. Must match the currently authenticated user.

Responses

Response samples

Content type
application/json
{
  • "statusCode": 201,
  • "success": true,
  • "message": "Passkey registration session has been successfully created.",
  • "data": {
    },
  • "metadata": {
    }
}

Verify and finalize new Passkey registration

Completes the registration of a new Passkey for the currently authenticated user.
This endpoint verifies the passkey attestation response generated by the client after initiating the "Add new passkey" process.

Once verification succeeds:

  • The passkey is securely registered and linked to the user’s account.
  • The corresponding challenge session is marked as consumed.
  • A success response containing the stored passkey details is returned.

Access to this endpoint requires a valid authenticated session and a matching user ID in the path parameter.

Authorizations:
AccessTokenCokie
path Parameters
userid
required
string
Example: 64f2d2ab8e2e1b03b6f3cd44

The unique identifier of the user who is adding a new passkey. Must match the currently authenticated user.

Request Body schema: application/json
required

Contains the passkey attestation response returned by the browser after a successful WebAuthn registration ceremony.
This data is verified server-side to ensure that the credential is valid, was generated for the expected challenge, and belongs to the authenticated user.

id
required
string

Base64Url-encoded credential ID generated by the authenticator.

rawId
required
string

Raw Base64Url-encoded credential ID.

type
required
string
Value: "public-key"

Must always be "public-key".

required
object
authenticatorAttachment
string
Enum: "cross-platform" "platform"

Optional attachment modality of the authenticator.

object

Optional results of any WebAuthn client extensions.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "rawId": "string",
  • "type": "public-key",
  • "response": {
    },
  • "authenticatorAttachment": "cross-platform",
  • "clientExtensionResults": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 201,
  • "message": "Passkey was successfully added.",
  • "data": {
    },
  • "metadata": {
    }
}

Initiate Passkey removal for a user

This endpoint initiates the process to remove a passkey associated with a user's account.
The user must be authenticated and authorized to remove a specific passkey, identified by the credentialid.
Upon successful initiation, a passkey removal session is created, and options for the passkey removal request (such as challenge data) are returned.
The challenge session is created to ensure that the request is authentic, and no unauthorized changes can be made to the passkey list.

Important:

  • The user must be authenticated using a valid access token (passed via cookies).
  • The userid and credentialid parameters must match the currently authenticated user and the passkey being removed.
Authorizations:
AccessTokenCokie
path Parameters
userid
required
string
Example: 64f2d2ab8e2e1b03b6f3cd44

The unique identifier of the user who is removing a passkey. This must match the authenticated user's ID. Only the user who owns the passkey can initiate the removal.

credentialid
required
string
Example: a1b2c3d4e5f6789ghijk01234lm56789

The unique identifier of the passkey credential that is being removed. This should match the credential ID of the passkey to be deleted.

Responses

Response samples

Content type
application/json
{
  • "statusCode": 201,
  • "success": true,
  • "message": "Passkey remove session has been successfully created.",
  • "data": {
    },
  • "metadata": {
    }
}

Remove a passkey credential from a user's account

This endpoint allows the authenticated user to remove a specific passkey credential from their account. The request must include the user ID and the credential ID of the passkey to be removed. The user can only remove their own passkeys. This action requires authentication and the provided session must be valid. If successful, the passkey will be permanently deleted from the system, and the session used for verification will be marked as consumed.

Authorizations:
AccessTokenCokie
path Parameters
userid
required
string
Example: 64f2d2ab8e2e1b03b6f3cd44

The unique identifier of the user who is removing a passkey. This must match the authenticated user's ID. Only the user who owns the passkey can initiate the removal.

credentialid
required
string
Example: a1b2c3d4e5f6789ghijk01234lm56789

The unique identifier of the passkey credential that is being removed. This should match the credential ID of the passkey to be deleted.

Request Body schema: application/json
required

The authentication response containing the necessary data for validating the passkey removal. This includes the signature and other relevant data to ensure the security of the operation.

id
required
string

The base64url-encoded credential ID uniquely identifying the passkey credential.

rawId
required
string

The raw credential ID in base64url format. Usually identical to id but encoded differently.

type
required
string
Value: "public-key"

The credential type. For WebAuthn, always "public-key".

authenticatorAttachment
string
Enum: "cross-platform" "platform"

Indicates the attachment modality of the authenticator:

  • "platform": built into the device (e.g. Touch ID, Windows Hello)
  • "cross-platform": external authenticator (e.g. security key)
object

Results from any WebAuthn extensions used during authentication.

required
object

Contains the raw cryptographic materials returned by the authenticator, required for verifying the authentication response.

Responses

Request samples

Content type
application/json
{
  • "id": "hT1lYyBBtU4QxZ5L5RjYuw",
  • "rawId": "hT1lYyBBtU4QxZ5L5RjYuw",
  • "type": "public-key",
  • "authenticatorAttachment": "platform",
  • "clientExtensionResults": {
    },
  • "response": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 201,
  • "message": "Passkey has been successfully removed.",
  • "data": { },
  • "metadata": {
    }
}

Retrieve all passkeys associated with a user.

This endpoint allows you to retrieve all passkeys that are associated with a specific user by their unique userid. The user must be authenticated and the userid in the path must match the authenticated user's ID to prevent unauthorized access. Each passkey returned will include essential details such as the credential ID, the associated provider (aaguid), the date it was created, and the last time it was used. The response also includes metadata with the total count of passkeys retrieved.

Authorizations:
AccessTokenCokie
path Parameters
userid
required
string
Example: 60c72b2f9f1b2c001c8a3e5f

The unique identifier of the user for whom the sessions are being retrieved.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "All passkeys were successfully retrieved.",
  • "data": {
    },
  • "metadata": {
    }
}

Session Module

Retrieve all active sessions for the authenticated user

Retrieves a list of all active login sessions associated with the authenticated user. This endpoint allows a user to view all currently valid sessions across devices and browsers, helping with account activity monitoring and session management.
Each returned session includes device information (userAgent), creation and expiration timestamps, and a boolean flag (isCurrent) indicating whether it corresponds to the current active session (the one used to make the request).
Expired sessions are automatically filtered out and are not included in the response.

Authorizations:
AccessTokenCokie

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "User sessions retrieved successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Retrieve the current user session

Retrieves the current active session for the authenticated user, based on the session ID stored in the request context. This endpoint is primarily used to identify the session associated with the current request and to retrieve minimal user information .

Authorizations:
AccessTokenCokie

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "User session retrieved successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Delete a user session by ID

Deletes a specific user session identified by its ID. The operation validates that the session exists and that the authenticated user has permission to delete it. If the deleted session is the current session of the user, authentication cookies will be cleared, effectively logging the user out. Responses include a success message and, if the current session was deleted, a nextStep indicating that the user should be redirected to the login page. Possible errors:

  • 403 Forbidden: If the user tries to delete a session that does not belong to them.
  • 404 Not Found: If the session ID does not exist.
Authorizations:
AccessTokenCokie
path Parameters
id
required
string
Example: 60c72b2f9f1b2c001c8a3e5f

The unique identifier of the session who will be deleted.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "User session successfully removed.",
  • "data": {
    },
  • "metadata": {
    }
}

OIDC Authentication Module

Generate Google OIDC authorization URL

Initiates the OAuth 2.0 Authorization Code Flow with PKCE for Google sign-in. This endpoint generates a unique state and code_challenge, stores them in the database as an OIDC session, and redirects the client to the Google OAuth 2.0 authorization endpoint. The state is used to prevent CSRF attacks, and code_challenge is part of PKCE to enhance security. Behavior: - Returns an HTTP 307 redirect to the Google authorization URL. - Sets caching headers to prevent storing sensitive information. - No JSON body is returned. Authorization URL parameters sent to Google: - access_type: Requests offline access to receive refresh tokens (offline) - response_type: Expected response type (code) - client_id: Google OAuth Client ID - scope: Requested access scopes (openid profile email) - redirect_uri: Callback URL registered in Google OAuth App - state: Randomly generated string to prevent CSRF - code_challenge and code_challenge_method: PKCE parameters (S256)

Responses

Response samples

Content type
application/json
{}

Authenticate user via Google OIDC callback

Handles the callback from Google after user authorization. Expects code and state query parameters returned by Google. Flow: 1. Verify that the state exists, has not expired, and has not been consumed. 2. Exchange the authorization code for tokens (access token, refresh token, ID token). 3. Validate the ID token against Google's JWKS endpoint and verify claims. 4. Create or find a corresponding user in the local database. 5. Set authentication cookies (accessToken and refreshToken). 6. Return a JSON response indicating successful login.

query Parameters
code
required
string

Authorization code returned by Google

state
required
string

Unique state generated during the authorization request

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication successful, you have been signed in successfully.",
  • "data": {
    },
  • "metadata": {
    }
}

Generate GitHub OIDC authorization URL

Initiates the OAuth 2.0 Authorization Code Flow with PKCE for GitHub sign-in. This endpoint generates a unique state and code_challenge, stores them in the database as an OIDC session, and redirects the client to the GitHub OAuth 2.0 authorization endpoint. The state is used to prevent CSRF attacks, and code_challenge is part of PKCE to enhance security. Behavior: - Returns an HTTP 307 redirect to the GitHub authorization URL. - Sets caching headers to prevent storing sensitive information. - No JSON body is returned. Authorization URL parameters sent to GitHub: - client_id: GitHub OAuth App client ID - redirect_uri: Callback URI registered in GitHub OAuth App - scope: Requested access scopes (user read:user user:email) - state: Randomly generated string to prevent CSRF - code_challenge and code_challenge_method: PKCE parameters - allow_signup: Whether GitHub should prompt to create a new account (true) - access_type: Offline access for refresh tokens (offline) - prompt: Account selection prompt (select_account)

Responses

Response samples

Content type
application/json
{}

Authenticate user via Github OIDC callback

Handles the callback from Github after user authorization. Expects code and state query parameters returned by Github. Flow: 1. Verify that the state exists, has not expired, and has not been consumed. 2. Exchange the authorization code for tokens (access token, refresh token, ID token). 3. Validate the ID token against Github's JWKS endpoint and verify claims. 4. Create or find a corresponding user in the local database. 5. Set authentication cookies (accessToken and refreshToken). 6. Return a JSON response indicating successful login.

query Parameters
code
required
string

Authorization code returned by Github

state
required
string

Unique state generated during the authorization request

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statusCode": 200,
  • "message": "Authentication successful, you have been signed in successfully.",
  • "data": {
    },
  • "metadata": {
    }
}