Authentication

Basefloor provides a comprehensive authentication system built around JWT tokens with support for user registration, login, email verification, and password reset functionality.

Features

• JWT-based authentication
• User registration and login
• Email verification
• Password reset functionality
• Token refresh capabilities
• Role-based access control

Configuration

Configure authentication in your basefloor.config.js:

module.exports = (API) => {
  return {
    auth: {
      enabled: true,
      jwt: {
        secret: process.env.JWT_SECRET || 'your-secret-key-change-in-production',
        expiresIn: '7d'
      }
    }
  }
}

User Model

Basefloor includes a built-in Users model with the following fields:

• email - User's email address (required, unique)
• password_hash - Hashed password
• name - User's display name
• role - User role for permissions
• email_verified - Email verification status
• created_at - Account creation timestamp
• updated_at - Last update timestamp

Authentication Endpoints

Register

Register a new user account:

POSThttp://localhost:3000/register

Base URL

Headers

Request Body

JSONForm DataRaw Text

{"email": "user@example.com", "password": "securePassword123", "name": "John Doe"}

Static Example:

POST /register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

Login

Authenticate a user and receive a JWT token:

POSThttp://localhost:3000/login

Base URL

Headers

Request Body

JSONForm DataRaw Text

{"email": "user@example.com", "password": "securePassword123"}

Response:

{
  "token": "jwt-token-here",
  "user": {
    "_id": "user-id",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}

Static Example:

POST /login
Content-Type: application/json

{
  "email": "user@example.com", 
  "password": "securepassword"
}

Verify Email

Verify a user's email address with a verification token:

POSThttp://localhost:3000/user/verify

Base URL

Headers

Request Body

JSONForm DataRaw Text

{"token": "verification-token-here"}

Static Example:

POST /user/verify
Content-Type: application/json

{
  "token": "verification-token"
}

Forgot Password

Request a password reset email:

POSThttp://localhost:3000/user/reset/password

Base URL

Headers

Request Body

JSONForm DataRaw Text

{"email": "user@example.com"}

Static Example:

POST /user/reset/password
Content-Type: application/json

{
  "email": "user@example.com"
}

Reset Password

Reset password using a reset token:

POSThttp://localhost:3000/user/reset/password

Base URL

Headers

Request Body

JSONForm DataRaw Text

{"token": "reset-token-here", "password": "newSecurePassword123"}

Static Example:

PUT /user/reset/password
Content-Type: application/json

{
  "token": "reset-token",
  "password": "newpassword"
}

Get Current User

Get the authenticated user's information:

GEThttp://localhost:3000/user

Base URL

Authentication

Bearer TokenBasic AuthNone

Query Parameters

Headers

Testing Authentication Flow

Complete Authentication Workflow

1. Register a new user using the registration endpoint above
2. Login with credentials to get a JWT token
3. Copy the token from the login response
4. Use the token in the "Get Current User" endpoint to verify authentication
5. Test protected endpoints using the token

💡 Pro Tip: After logging in, copy the JWT token from the response and paste it into the "Bearer Token" field of other authenticated endpoints to test them.

Using Authentication in Routes

Protect your routes by adding authentication requirements:

{
  routes: [
    {
      _id: '/protected-resource(Model)',
      _create: { 
        allow: true,  // Requires valid JWT token
        inject: { user_id: '@user._id' }  // Inject authenticated user ID
      },
      _read: { 
        allow: '@_user.user_id=@user._id'  // Only allow access to own resources
      }
    }
  ]
}

Permission Checks

Use the authenticated user in permission rules:

• @user._id - Authenticated user's ID
• @user.email - Authenticated user's email
• @user.role - Authenticated user's role
• @user.email_verified - Email verification status

Example permission rules:

{
  allow: '@user.role=admin',  // Only admins
  allow: '@user.email_verified=true',  // Only verified users
  allow: '@_user.owner_id=@user._id'  // Only resource owner
}

Custom User Fields

Extend the Users model with custom fields:

{
  models: {
    Users: {
      values: {
        // Default fields...
        department: ['String', 'cru'],
        phone: ['String', 'cru'],
        preferences: ['Object', 'cru', {}]
      }
    }
  }
}

Security Best Practices

1. Use strong JWT secrets: Generate cryptographically secure secrets
2. Enable email verification: Prevent unauthorized account creation
3. Set appropriate token expiration: Balance security with user experience
4. Use HTTPS: Always serve authentication endpoints over HTTPS
5. Validate input: basefloor provides built-in validation for auth endpoints

Error Handling

Authentication endpoints return standard HTTP status codes:

• 200 - Success
• 400 - Bad request (validation error)
• 401 - Unauthorized (invalid credentials/token)
• 403 - Forbidden (account not verified, etc.)
• 404 - Not found (user doesn't exist)
• 500 - Server error

Integration with Email

Configure email settings for verification and password reset:

{
  email: {
    provider: 'postmark',
    from: 'noreply@yourdomain.com',
    templates: {
      emailVerification: 'template-id',
      passwordReset: 'template-id'
    }
  }
}

Environment Configuration

Development

API_BASE_URL=http://localhost:3000
JWT_SECRET=dev-secret-key
EMAIL_PROVIDER=console  # Logs emails to console

Production

API_BASE_URL=https://api.yourdomain.com
JWT_SECRET=your-secure-production-secret
EMAIL_PROVIDER=postmark
POSTMARK_SERVER_TOKEN=your-postmark-token

Testing Authentication

Test your authentication endpoints using the interactive tools above, or use these command-line examples:

# Set your API base URL
API_BASE_URL="https://api.yourdomain.com"  # Production
# API_BASE_URL="http://localhost:3000"     # Development

# Register a new user
curl -X POST ${API_BASE_URL}/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","name":"Test User"}'

# Login
curl -X POST ${API_BASE_URL}/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Use the token in protected requests
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  ${API_BASE_URL}/user

Next Steps

• Test the endpoints using the interactive tools above
• Configure email services for verification and password reset
• Set up proper environment variables for your deployment
• Implement frontend authentication using the Code Playground examples
• Explore the API Explorer for more advanced testing