Authentication API

SonicJs provides a comprehensive set of authentication endpoints to handle user authentication, email confirmation, password resets, and session management.

This includes the ability to:

  1. Register new users
  2. Login with email/password or OTP
  3. Manage user sessions (get current user, logout)
  4. Handle password resets
  5. Send and receive email confirmations
  6. Check email existence and confirmation status
POST/api/v1/auth/login

Login

This endpoint allows you to authenticate a user and receive a session token.

Required attributes

  • Name
    email
    Type
    string
    Description

    The user's email address

  • Name
    password
    Type
    string
    Description

    The user's password

  • Name
    otp
    Type
    string
    Description

    One-time password (optional - used for one-time password login)

Return Data

  • Name
    bearer
    Type
    string
    Description

    The session token to be used in subsequent requests

  • Name
    expires
    Type
    number
    Description

    The expiration timestamp for the session

Request

POST
/api/v1/auth/login
{
  "email": "[email protected]",
  "password": "userpassword"
}

Response (200)

{
  "bearer": "session-token",
  "expires": 1748293651641
}

Response (401)

{
  "error": "Invalid email/password combination"
}
POST/api/v1/users

Register User

This endpoint allows you to register a new user in the system.

Required attributes

  • Name
    email
    Type
    string
    Description

    The user's email address

  • Name
    password
    Type
    string
    Description

    The user's password

  • Name
    firstName
    Type
    string
    Description

    The user's first name

  • Name
    lastName
    Type
    string
    Description

    The user's last name

Optional attributes

  • Name
    role
    Type
    string
    Description

    The user's role (defaults to "user")

  • Name
    profile
    Type
    object
    Description

    Additional user profile information

Return Data

  • Name
    data
    Type
    object
    Description

    The created user data

Request

POST
/api/v1/users
{
  "data": {
    "email": "[email protected]",
    "password": "userpassword",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "profile": {
      "company": "Example Corp",
      "position": "Developer"
    }
  }
}

Response (201)

{
  "data": {
    "id": "2026ad2d-2dc2-4187-9809-7ade12d621b1",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "profile": {
      "company": "Example Corp",
      "position": "Developer"
    },
    "createdOn": 1748293651641,
    "updatedOn": 1748293651641
  }
}

Response (400)

{
  "error": "Email already exists"
}

Response (400)

{
  "error": "Invalid email format"
}
GET/api/v1/auth/user

Current User

This endpoint returns information about the current user session.

Required Headers

  • Name
    Authorization
    Type
    string
    Description

    Bearer token for authentication

Return Data

  • Name
    data
    Type
    object
    Description

    Contains user and session information

Request

GET
/api/v1/auth/user
http://localhost:4321/api/v1/auth/user -H "Authorization: Bearer session-token"

Response (200)

{
  "data": {
    "user": {
      "id": "2026ad2d-2dc2-4187-9809-7ade12d621b1",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "profile": {}
    },
    "session": {
      "userId": "2026ad2d-2dc2-4187-9809-7ade12d621b1",
      "activeExpires": 1748293651641,
      "idleExpires": 1748293651641,
      "token": "session-token"
    }
  }
}

Response (401)

{
  "error": "No token provided or invalid token"
}
POST/api/v1/auth/logout

Logout

This endpoint invalidates the current session.

Required Headers

  • Name
    Authorization
    Type
    string
    Description

    Bearer token for authentication

Return Data

  • Name
    message
    Type
    string
    Description

    Success message

Request

POST
/api/v1/auth/logout
http://localhost:4321/api/v1/auth/logout -H "Authorization: Bearer session-token"

Response (200)

{
  "message": "Successfully logged out"
}
GET/api/v1/auth/password/reset/send/{email}

Password Reset

This endpoint sends a password reset email to the specified email address.

Required attributes

  • Name
    email
    Type
    string
    Description

    URL-encoded email address to send reset link to

Return Data

  • Name
    message
    Type
    string
    Description

    Success message

Request

GET
/api/v1/auth/password/reset/send/user%40example.com
http://localhost:4321/api/v1/auth/password/reset/send/user%40example.com

Response (200)

{
  "message": "If the email address is valid, a password reset email has been sent"
}
POST/api/v1/auth/password/reset/receive

Password Reset Receive

This endpoint resets the user's password using a reset code.

Required attributes

  • Name
    email
    Type
    string
    Description

    User's email address

  • Name
    password
    Type
    string
    Description

    New password

  • Name
    code
    Type
    string
    Description

    Password reset code from email

Return Data

  • Name
    message
    Type
    string
    Description

    Success message

Request

POST
/api/v1/auth/password/reset/receive
{
  "email": "[email protected]",
  "password": "newpassword",
  "code": "reset-code"
}

Response (200)

{
  "message": "Password updated successfully"
}

Response (400)

{
  "error": "Invalid reset code, expired code, or missing fields"
}
GET/api/v1/auth/password/otp/{email}

One-Time Password (OTP)

This endpoint sends a one-time password to the specified email address.

Required attributes

  • Name
    email
    Type
    string
    Description

    URL-encoded email address to send OTP to

Return Data

  • Name
    message
    Type
    string
    Description

    Success message

Request

GET
/api/v1/auth/password/otp/user%40example.com
http://localhost:4321/api/v1/auth/password/otp/user%40example.com

Response (200)

{
  "message": "OTP sent successfully"
}

Response (404)

{
  "error": "User not found"
}
GET/api/v1/auth/email-confirmation/send/{email}

Email Confirmation

This endpoint sends an email confirmation link to the specified email address.

Required attributes

  • Name
    email
    Type
    string
    Description

    URL-encoded email address to send confirmation to

Return Data

  • Name
    message
    Type
    string
    Description

    Success message

Request

GET
/api/v1/auth/email-confirmation/send/user%40example.com
http://localhost:4321/api/v1/auth/email-confirmation/send/user%40example.com

Response (200)

{
  "message": "Confirmation email sent"
}
GET/api/v1/auth/email-confirmation/receive/{code}

Email Confirmation Receive

This endpoint confirms the user's email address using the confirmation code.

Required attributes

  • Name
    code
    Type
    string
    Description

    Email confirmation code

Return Data

Redirects to the configured EMAIL_CONFIRMATION_REDIRECT_URL

Request

GET
/api/v1/auth/email-confirmation/receive/confirmation-code
http://localhost:4321/api/v1/auth/email-confirmation/receive/confirmation-code
GET/api/v1/auth/email-exists/{email}

Email Existence Check

This endpoint checks if an email address exists in the system and if it has been confirmed.

Required attributes

  • Name
    email
    Type
    string
    Description

    URL-encoded email address to check

Return Data

  • Name
    exists
    Type
    boolean
    Description

    Whether the email exists in the system

  • Name
    confirmed
    Type
    boolean
    Description

    Whether the email has been confirmed

Request

GET
/api/v1/auth/email-exists/user%40example.com
http://localhost:4321/api/v1/auth/email-exists/user%40example.com

Response (200)

{
  "exists": true,
  "confirmed": true
}

Security Notes

The authentication system implements several security measures:

  1. All endpoints use secure session management with expiration times
  2. Passwords are hashed using Argon2
  3. Session tokens are generated using secure random strings
  4. Email confirmation and password reset links have expiration times
  5. OTP codes are single-use and expire after a configured time period
  6. The system supports invalidating all user sessions on login if configured

Environment Variables

The following environment variables are used by the authentication system:

  • Name
    REQUIRE_EMAIL_CONFIRMATION
    Type
    boolean
    Description

    Enable/disable email confirmation requirement

  • Name
    EMAIL_CONFIRMATION_REDIRECT_URL
    Type
    string
    Description

    URL to redirect after email confirmation

  • Name
    ONE_TIME_PASSWORD_EXPIRATION_TIME
    Type
    number
    Description

    OTP expiration time in milliseconds

  • Name
    RESET_PASSWORD_EXPIRATION_TIME
    Type
    number
    Description

    Password reset link expiration time

  • Name
    INVALIDATE_USER_SESSIONS
    Type
    boolean
    Description

    Whether to invalidate all user sessions on login

  • Name
    EMAIL_FROM
    Type
    string
    Description

    Email address for system emails

  • Name
    EMAIL_BASE_URL
    Type
    string
    Description

    Base URL for email links

Next Steps

The authentication endpoints provide you with a solid foundation for user management. For more advanced features, you may want to check out the docs for SonicJS routing to create custom authentication flows.