API Endpoints

Complete reference for all Users API endpoints.

Public Endpoints

These endpoints are publicly accessible and use the x-app-id header for app identification.

Create or Update User

Create a new user or update an existing one (upsert by email).

Endpoint: POST /v1/users

Headers:

• Content-Type: application/json (required)
• x-app-id: <your-app-id> (required)

Request Body:

{
  "email": "user@example.com",
  "data": {
    "fullName": "John Doe",
    "age": "30",
    "consentRequired": true,
    "consentOptional": false
  }
}

Response: 200 OK

{
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Notes:

• Email is normalized (lowercased, trimmed) and deduplicated per app
• If a user with the same email exists, the record is updated instead of created
• The data object must conform to your app's schema (see Schema Endpoint)

Error Responses:

• 400 Bad Request: Invalid request body or schema validation failed
• 400 Bad Request: Missing or invalid x-app-id header

Get Schema

Retrieve the user schema for your app.

Endpoint: GET /v1/schema

Headers:

• x-app-id: <your-app-id> (required)

Response: 200 OK

{
  "version": 1,
  "rejectUnknown": true,
  "fields": [
    {
      "key": "fullName",
      "label": "Full name",
      "kind": "text",
      "required": false,
      "minLength": 1,
      "maxLength": 200
    },
    {
      "key": "consentRequired",
      "label": "Consent (required)",
      "kind": "checkbox",
      "required": true
    }
  ]
}

Field Types:

• text: String field with optional minLength, maxLength, and regex constraints
• checkbox: Boolean field (if required: true, must be true)
• select: String field with enum array of allowed values
• number: Numeric field with optional min and max constraints
• date: String field containing an ISO date string

Error Responses:

• 400 Bad Request: Missing or invalid x-app-id header

Health Check

Check if the API is running.

Endpoint: GET /health

Response: 200 OK

{
  "status": "ok"
}

Authentication Endpoints

These endpoints require cookie-based session authentication.

Login

Authenticate with your app credentials to access protected endpoints.

Endpoint: POST /auth/login

Request Body:

{
  "sourceAppId": "my-app-id",
  "password": "your-password"
}

Response: 200 OK

{
  "ok": true,
  "sourceAppId": "my-app-id",
  "role": "user"
}

Notes:

• Sets a secure HTTP-only cookie for session management
• Session expires after 7 days
• Use this endpoint to access the admin dashboard

Error Responses:

• 400 Bad Request: Missing or invalid sourceAppId or password
• 401 Unauthorized: Invalid credentials

Logout

End the current session.

Endpoint: POST /auth/logout

Response: 200 OK

{
  "ok": true
}

Get Session

Check current authentication status.

Endpoint: GET /auth/session

Response: 200 OK (authenticated)

{
  "sourceAppId": "my-app-id",
  "role": "user"
}

Response: 401 Unauthorized (not authenticated)

{
  "message": "Not authenticated"
}

User Management Endpoints

These endpoints require authentication and return data scoped to your app.

List Users

Get all users for your app.

Endpoint: GET /auth/users

Headers:

• Cookie: sid=<session-cookie> (set by login)

Response: 200 OK

{
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "data": {
        "fullName": "John Doe",
        "age": "30",
        "consentRequired": true
      },
      "schemaVersion": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Notes:

• Returns users sorted by creation date (newest first)
• Only returns users for your app's sourceAppId
• Requires authenticated session

Error Responses:

• 401 Unauthorized: Not authenticated

Admin Endpoints

These endpoints require admin role authentication.

List All Apps

Get all apps in the system (admin only).

Endpoint: GET /auth/apps

Response: 200 OK

{
  "apps": [
    {
      "sourceAppId": "my-app-id",
      "role": "user",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Create App

Create a new app with auto-generated credentials (admin only).

Endpoint: POST /auth/apps

Request Body:

{
  "sourceAppId": "new-app-id"
}

Response: 200 OK

{
  "sourceAppId": "new-app-id",
  "role": "user",
  "password": "xK9mP2vQ7nR4tY8w"
}

Notes:

• Password is shown only once - save it securely!
• sourceAppId must be 1-80 characters, alphanumeric + dots/underscores/hyphens
• App starts with default schema (see Schema Management)

Error Responses:

• 400 Bad Request: Invalid sourceAppId format
• 409 Conflict: App with this sourceAppId already exists
• 403 Forbidden: Requires admin role

Delete App

Delete an app and all its users (admin only).

Endpoint: DELETE /auth/apps/:sourceAppId

Response: 200 OK

{
  "ok": true,
  "deletedUsers": 42
}

Notes:

• Cannot delete admin apps
• Permanently deletes all users for the app

Error Responses:

• 400 Bad Request: Cannot delete admin app
• 404 Not Found: App not found
• 403 Forbidden: Requires admin role

List All Users (Admin)

Get users across all apps with optional filtering (admin only).

Endpoint: GET /auth/admin/users

Query Parameters:

• sourceAppId (optional): Filter by app ID
• limit (optional): Results per page (default: 50, max: 200)
• skip (optional): Pagination offset (default: 0)

Example: GET /auth/admin/users?sourceAppId=my-app&limit=10&skip=0

Response: 200 OK

{
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "sourceAppId": "my-app",
      "email": "user@example.com",
      "data": {
        "fullName": "John Doe"
      },
      "schemaVersion": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "limit": 10,
  "skip": 0
}

Schema Management

Admin endpoints for managing app schemas.

Get App Schema

Get the schema for a specific app (admin only).

Endpoint: GET /auth/apps/:sourceAppId/schema

Response: 200 OK

{
  "version": 1,
  "rejectUnknown": true,
  "fields": [
    {
      "key": "fullName",
      "label": "Full name",
      "kind": "text",
      "required": false,
      "maxLength": 200
    }
  ]
}

Update App Schema

Update the schema for a specific app (admin only).

Endpoint: PUT /auth/apps/:sourceAppId/schema

Request Body:

{
  "rejectUnknown": true,
  "fields": [
    {
      "key": "fullName",
      "label": "Full name",
      "kind": "text",
      "required": true,
      "minLength": 1,
      "maxLength": 200
    },
    {
      "key": "consentRequired",
      "label": "Consent",
      "kind": "checkbox",
      "required": true
    },
    {
      "key": "age",
      "label": "Age",
      "kind": "number",
      "required": false,
      "min": 0,
      "max": 120
    },
    {
      "key": "country",
      "label": "Country",
      "kind": "select",
      "required": false,
      "enum": ["US", "CA", "UK", "DE"]
    }
  ]
}

Response: 200 OK

{
  "version": 2,
  "rejectUnknown": true,
  "fields": [...]
}

Notes:

• Schema version is automatically incremented
• Existing user data is not validated against new schema
• New user submissions must conform to the updated schema
• Field keys must match regex: ^[a-zA-Z][a-zA-Z0-9_]{0,50}$
• Maximum 100 fields per schema

Error Responses:

• 400 Bad Request: Invalid schema format
• 404 Not Found: App not found
• 403 Forbidden: Requires admin role