User Management

Comprehensive user management with JWT-based authentication, RBAC authorization, and complete user lifecycle management.

User Lifecycle

1. Registration (First User)

Creating an Organization

POST /api/v1/auth/register
{
  "email": "admin@example.com",
  "password": "SecurePassword123!",
  "organization_name": "Acme Corp"
}

Creates:

  • ✅ New organization
  • ✅ User account (Owner role)
  • ✅ Default project
  • ✅ JWT token

2. Invitation (Additional Users)

Invite Users to Organization

POST /api/v1/users/invite
Authorization: Bearer <token>
{
  "email": "engineer@example.com",
  "role": "member",
  "projects": ["project-uuid"]
}

Process:

  1. 1. Email sent to user
  2. 2. User clicks invitation link
  3. 3. User sets password
  4. 4. User gains access

3. Login

User Authentication

POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "member",
    "organization_id": "org-uuid"
  },
  "expires_at": "2025-11-10T12:00:00Z"
}

4. Password Reset

Forgot Password

POST /api/v1/auth/forgot-password
{
  "email": "user@example.com"
}

Process:

  1. 1. Reset email sent
  2. 2. User clicks reset link (valid 1 hour)
  3. 3. User enters new password
  4. 4. Password updated, old sessions invalidated

Authentication

JWT Tokens

Stateless authentication with JWT tokens. Tokens expire after 7 days by default.

Password Security

Bcrypt hashing with salt rounds. Minimum 8 characters, recommended 12+.

Email Verification

Optional email verification for new accounts (configurable).

Session Management

Multiple active sessions supported. Revoke all sessions on password change.

User Operations

List Users

GET /api/v1/users
Authorization: Bearer <token>

# Requires: Admin or Owner role

Update User Role

PATCH /api/v1/users/:user_id/role
Authorization: Bearer <token>
{
  "role": "admin"
}

# Requires: Admin or Owner role

Remove User

DELETE /api/v1/users/:user_id
Authorization: Bearer <token>

# Requires: Admin or Owner role
# Cannot remove yourself
# Cannot remove last Owner

Best Practices

🔒 Strong Passwords: Require minimum 12 characters with mix of uppercase, lowercase, numbers, and symbols.

👥 Offboarding Process: Remove users immediately when they leave the organization. Review and reassign their projects first.

📧 Verify Email Addresses: Always verify email addresses before granting access to prevent unauthorized access.