User Auth API

POST /api/auth/custom-token

Sign in a user with email and password. Returns a Firebase custom token and user profile.

Request Body

Request Body

{
  "clientId": "string", // Required. The client (tenant) ID
  "email": "string", // Required. User's email address
  "password": "string" // Required. User's password
}

Response

• 200 OK:

  Success Response

  {
    "customToken": "string", // Firebase custom token
    "user": {
      "uid": "string",
      "email": "string",
      "displayName": "string|null",
      "photoURL": "string|null",
      "emailVerified": true,
      "disabled": false
    }
  }

• 400 Bad Request: { "error": "Missing clientId" | "Missing email or password" }

• 401 Unauthorized: { "error": "Invalid credentials" | "<Firebase error message>" }

• 404 Not Found: { "error": "Client user not found" }

• 500 Internal Server Error: { "error": "Internal server error" | "Server misconfiguration: missing Firebase API key" }

User Profile Fields

Field	Type	Description
uid	string	Firebase user ID
email	string	User's email address
displayName	string | null	User's display name
photoURL	string | null	User's profile photo URL
emailVerified	boolean	Whether the user's email is verified
disabled	boolean	Whether the user account is disabled

note

For Google or other OAuth sign-in, use the Firebase JS SDK directly on the frontend.

• Returns a Firebase custom token for use with client SDKs.
• All error responses include an error field with a descriptive message.

---

Set Custom Claims API

POST /api/auth/set-claims

Sets custom Firebase Auth claims for a user, based on their client user document. Returns the updated claims and user profile.

Request

Headers:

• Content-Type: application/json

Body:

Request Body

{
  "clientId": "string", // Required. The client (tenant) ID
  "idToken": "string" // Required. Firebase ID token for the user
}

Response

• 200 OK:

  Success Response

  {
    "success": true,
    "claims": {
      /* Custom claims object */
    },
    "user": {
      "uid": "string",
      "email": "string",
      "displayName": "string|null",
      "photoURL": "string|null",
      "emailVerified": true,
      "disabled": false
    }
  }

• 400 Bad Request: { "error": "Missing clientId" | "Missing idToken" }

• 401 Unauthorized: { "error": "Invalid idToken" }

• 404 Not Found: { "error": "Client user not found" | "Client user data missing" }

• 500 Internal Server Error: { "error": "Internal server error" }

Example Error Responses

Missing clientId

{ "error": "Missing clientId" }

Invalid idToken

{ "error": "Invalid idToken" }

Client user not found

{ "error": "Client user not found" }

Notes

• The endpoint verifies the provided Firebase ID token and looks up the user under /Clients/{clientId}/ClientUsers/{uid} in Firestore.
• If the user is found, custom claims are generated and set using the user’s client data.
• Only fields defined in the schema are accepted; unknown fields will result in a 400 error.
• This endpoint is typically used after user registration or when updating user roles/status.
• Super admin logic: Not directly handled here, but claims can be set for any user if the caller has a valid ID token and the user exists in the client.

Related

• See /api/auth/custom-token for obtaining a Firebase custom token.
• See the ClientUser schema in src/models/client-user.ts for user document structure.