POST /auth

Receives a Firebase ID token in the Authorization header (Bearer token). Verifies the token, checks if the user exists in the database based on Firebase UID. If the user exists, returns user data and a JWT for subsequent API calls. If the user doesn't exist, it implicitly creates the user based on the token and returns the new user data and a JWT.

Responses

  • 200 application/json

    Authentication successful (User already exists)

    Hide response attributes Show response attributes object
    • success boolean Required
    • statusCode integer Required
    • message string Required
    • data object Required
      Hide data attributes Show data attributes object
      • user object
        Hide user attributes Show user attributes object
        • id string Required

          Unique internal identifier for the user (CUID)

        • email string(email) Required

          User's email address (from Firebase)

        • role string Required

          User's role (e.g., 'user', 'admin')

          Default value is user.

        • name string

          User's name (from Firebase)

        • address string | null

          User's address (managed separately)

        • picture string | null

          URL to the user's profile picture (from Firebase)

        • user_id string Required

          Firebase User ID (UID)

        • verified boolean

          User verification status (from Firebase, default false)

      • token string

        JWT token for subsequent API requests (valid for 30 days)
  • 201 application/json

    Authentication successful (New user implicitly registered)

    Hide response attributes Show response attributes object
    • success boolean Required
    • statusCode integer Required
    • message string Required
    • data object Required
      Hide data attributes Show data attributes object
      • user object
        Hide user attributes Show user attributes object
        • id string Required

          Unique internal identifier for the user (CUID)

        • email string(email) Required

          User's email address (from Firebase)

        • role string Required

          User's role (e.g., 'user', 'admin')

          Default value is user.

        • name string

          User's name (from Firebase)

        • address string | null

          User's address (managed separately)

        • picture string | null

          URL to the user's profile picture (from Firebase)

        • user_id string Required

          Firebase User ID (UID)

        • verified boolean

          User verification status (from Firebase, default false)

      • token string

        JWT token for subsequent API requests (valid for 30 days)
  • 401 application/json

    Unauthorized (Invalid or missing Firebase token)

    Hide response attributes Show response attributes object
    • success boolean Required
    • statusCode integer Required
    • message string Required
  • 404 application/json

    User not found (Should not happen with implicit registration, but possible if DB check fails unexpectedly)

    Hide response attributes Show response attributes object
    • success boolean Required
    • statusCode integer Required
    • message string Required
  • 500 application/json

    Internal Server Error

    Hide response attributes Show response attributes object
    • success boolean Required
    • statusCode integer Required
    • message string Required
POST /auth 
curl \
 --request POST 'https://referspecs-backend.onrender.com/api/v1/auth'
Response examples (200) 
{
  "success": true,
  "statusCode": 200,
  "message": "Authentication successful",
  "data": {
    "user": {
      "id": "string",
      "email": "hello@example.com",
      "role": "user",
      "name": "string",
      "address": "string",
      "picture": "string",
      "user_id": "string",
      "verified": true
    },
    "token": "string"
  }
}
Response examples (201) 
{
  "success": true,
  "statusCode": 200,
  "message": "Authentication successful",
  "data": {
    "user": {
      "id": "string",
      "email": "hello@example.com",
      "role": "user",
      "name": "string",
      "address": "string",
      "picture": "string",
      "user_id": "string",
      "verified": true
    },
    "token": "string"
  }
}
Response examples (401) 
{
  "success": false,
  "statusCode": 400,
  "message": "Error description"
}
Response examples (404) 
{
  "success": false,
  "statusCode": 400,
  "message": "Error description"
}
Response examples (500) 
{
  "success": false,
  "statusCode": 400,
  "message": "Error description"
}