Identity & End-User Authentication

// When creating your schema, mark an entity as Identity
// This enables end-user authentication for YOUR application's users

// Via MCP (AI Assistant)
"Create a Customer entity with email and password fields,
 and mark it as the identity entity using email as the identifier"

// The AI creates:
{
  "name": "Customer",
  "fields": [
    { "name": "email", "type": "STRING", "required": true, "unique": true },
    { "name": "password", "type": "PASSWORD", "required": true },
    { "name": "name", "type": "STRING" },
    { "name": "phone", "type": "STRING" }
  ],
  "isIdentity": true,           // This entity provides authentication
  "identifierField": "email"    // Users log in with their email
}

// Your app's end users register via the identity endpoints
// FLXBL handles password hashing, validation, and email verification

POST /api/v1/identity/{tenantId}/register
{
  "email": "customer@example.com",
  "password": "SecurePassword123",
  "name": "Jane Customer",
  "phone": "+1-555-0123"
}

// Response
{
  "id": "node_abc123",
  "message": "Registration successful. Please check your email to verify your account."
}

// End users authenticate and receive JWT tokens
POST /api/v1/identity/{tenantId}/login
{
  "identifier": "customer@example.com",
  "password": "SecurePassword123"
}

// Response
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rf_abc123def456...",
  "expiresIn": 900,  // 15 minutes in seconds
  "user": {
    "id": "node_abc123",
    "email": "customer@example.com",
    "name": "Jane Customer",
    "phone": "+1-555-0123"
    // Note: password field is automatically redacted
  }
}

// When access token expires, use refresh token to get a new one
POST /api/v1/identity/{tenantId}/refresh
{
  "refreshToken": "rf_abc123def456..."
}

// Response
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900
}

// Authenticated end users can retrieve their profile
GET /api/v1/identity/{tenantId}/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Response
{
  "id": "node_abc123",
  "email": "customer@example.com",
  "name": "Jane Customer",
  "phone": "+1-555-0123",
  "_isVerified": true
}

// Step 1: Request password reset
POST /api/v1/identity/{tenantId}/forgot-password
{
  "identifier": "customer@example.com"
}
// Always returns success (prevents user enumeration)

// Step 2: User receives email with reset token
// Step 3: Reset password with token
POST /api/v1/identity/{tenantId}/reset-password
{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword456"
}

// Get current identity configuration (admin only)
GET /api/v1/identity/config
Authorization: Bearer {admin_token}

// Response
{
  "accessTokenExpiryMinutes": 15,
  "refreshTokenExpiryDays": 7,
  "minPasswordLength": 8,
  "requireEmailVerification": true
}

// Update identity configuration (admin only)
PATCH /api/v1/identity/config
Authorization: Bearer {admin_token}
{
  "accessTokenExpiryMinutes": 30,
  "refreshTokenExpiryDays": 14,
  "minPasswordLength": 12,
  "requireEmailVerification": true
}

// Using the FLXBL MCP tool
// In Cursor/Windsurf, ask the AI:

"View my current identity configuration"
// AI uses configure_identity with action: "get"

"Update token expiry to 30 minutes access 
 and 14 days refresh"
// AI uses configure_identity with action: "update"

// Customize verification email template (Handlebars)
PATCH /api/v1/identity/config
{
  "verificationEmailTemplate": "
    <h1>Welcome to {{tenantName}}!</h1>
    <p>Hi there! Click below to verify your email:</p>
    <a href='{{verificationLink}}'>Verify Email</a>
    <p>This link expires in 24 hours.</p>
  "
}

// Available template variables:
// {{tenantName}} - Your tenant name
// {{verificationLink}} - The verification URL
// {{userEmail}} - User's email address

// Customize password reset email
PATCH /api/v1/identity/config
{
  "passwordResetEmailTemplate": "
    <h1>Reset Your Password</h1>
    <p>Click below to reset your password:</p>
    <a href='{{resetLink}}'>Reset Password</a>
    <p>If you didn't request this, ignore this email.</p>
  "
}

// Available template variables:
// {{resetLink}} - The password reset URL
// {{userEmail}} - User's email address
// {{tenantName}} - Your tenant name