Skip to content

User Service API

👥

A comprehensive user management and authentication REST API built with Java, Spring Boot, and PostgreSQL. Manages user profiles, authentication, authorization, roles, and permissions.

Features

Feature Description Icon
User Registration Create user accounts with email verification ✍️
Authentication OAuth2, JWT, and session-based authentication 🔐
Passkey Authentication WebAuthn/FIDO2 passwordless authentication support 🔑
Social Login OAuth2 integration with popular social providers 👥
Authorization Role-based and attribute-based access control 🔑
Profile Management Manage user information and preferences 👤
Password Management Secure password reset and change mechanisms 🔒
Multi-Factor Auth Support for 2FA, authenticator apps, and biometrics 📱
Multi-Tenant Support Isolate users per tenant 🏢

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(UserController)
    B --> C[AuthenticationService]
    C --> D[UserService]
    C --> E[AuthorizationService]
    D --> F[UserRepository]
    E --> G[RoleRepository]
    F --> H[(PostgreSQL)]
    G --> H
    C --> I[JWT Provider]
    C --> J[Email Service]
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Authentication

Method Endpoint Description Request Body
POST /api/v1/auth/register Register a new user Email, password
POST /api/v1/auth/login User login Username/email, password, OTP
POST /api/v1/auth/refresh Refresh access token Refresh token
POST /api/v1/auth/mfa/qr Get TOTP QR for MFA enrollment
POST /api/v1/auth/mfa/verify Verify OTP and enable MFA OTP code
POST /api/v1/auth/forgot-password Request password reset Email
POST /api/v1/auth/reset-password Reset user password Email, token, newPassword
POST /api/v1/auth/social-login/url Get social login authorization URL provider, redirectUri
POST /api/v1/auth/social-login Social login with OAuth providers provider, code, redirectUri, state

User Management

Method Endpoint Description Request Body
GET /api/v1/users List all users (paginated) q, roleId, page, size
POST /api/v1/users Create a new user CreateUserDto
GET /api/v1/users/{userId} Get user by ID
PUT /api/v1/users/{userId} Update user details UpdateUserDto
POST /api/v1/users/{userId}/deactivate Deactivate a user
POST /api/v1/users/{userId}/reactivate Reactivate a user

Passkey Authentication

Method Endpoint Description Request Body
GET /api/v1/passkeys List user's passkeys (paginated) page, size, sort
POST /api/v1/passkeys/register/start Start passkey registration username
POST /api/v1/passkeys/register/finish Complete passkey registration credentialId, attestationObject, clientDataJSON, publicKey, transports, sessionToken
POST /api/v1/passkeys/authenticate/start Start passkey authentication username
POST /api/v1/passkeys/authenticate/finish Complete passkey authentication credentialId, authenticatorData, clientDataJSON, signature, userHandle, sessionToken
PUT /api/v1/passkeys/{credentialId} Update passkey name name
DELETE /api/v1/passkeys/{credentialId} Delete a passkey

Role Management

Method Endpoint Description Request Body
GET /api/v1/roles Get all roles (paginated) q, page, size
POST /api/v1/roles Create a new role CreateRoleDto
GET /api/v1/roles/{roleId} Get role by ID
PUT /api/v1/roles/{roleId} Update role details UpdateRoleDto
DELETE /api/v1/roles/{roleId} Delete a role
POST /api/v1/roles/{roleId}/assign-user/{userId} Assign role to user
DELETE /api/v1/roles/{roleId}/remove-user/{userId} Remove role from user

Permission Management

Method Endpoint Description Request Body
GET /api/v1/permissions List all permissions (paginated) q, page, size
POST /api/v1/permissions Create a new permission CreatePermissionDto
POST /api/v1/permissions/bulk Bulk create permissions Array of CreatePermissionDto
DELETE /api/v1/permissions/bulk Bulk delete permissions Array of permission names
POST /api/v1/permissions/add-to-role/{roleId} Add permissions to role Array of permission UUIDs
POST /api/v1/permissions/remove-from-role/{roleId} Remove permissions from role Array of permission UUIDs

Password Management

Method Endpoint Description Request Body
POST /api/v1/password/request-reset Request password reset Email
POST /api/v1/password/reset Reset user password Email, token, newPassword
POST /api/v1/password/change Change user password userId, email, token, oldPassword, newPassword

Tenant Management

Method Endpoint Description Request Body
GET /api/v1/tenants Get all tenants (paginated) q, page, size
POST /api/v1/tenants Create a new tenant CreateTenantDto
GET /api/v1/tenants/{tenantId} Get tenant by ID
PUT /api/v1/tenants/{tenantId} Update tenant details UpdateTenantDto
DELETE /api/v1/tenants/{tenantId} Delete a tenant
PATCH /api/v1/tenants/{tenantId}/status Update tenant status status (ACTIVE, INACTIVE, SUSPENDED, PENDING)
GET /api/v1/tenants/{tenantId}/users/{username}/mfa-status Get user MFA status

Address Management

Method Endpoint Description Request Body
POST /api/v1/addresses Create user address CreateAddressDto
PUT /api/v1/addresses Update address details UpdateAddressDto

Sequence: User Registration and Login

sequenceDiagram
    participant U as User
    participant API as UserController
    participant Auth as AuthenticationService
    participant US as UserService
    participant Repo as UserRepository
    participant Email as EmailService
    U->>API: POST /users/register (email, password)
    API->>Auth: validate input
    Auth->>US: create user
    US->>Repo: save user
    Repo-->>US: user created
    US->>Email: send verification email
    Email-->>US: email queued
    US-->>API: UserRegistrationResponse
    API-->>U: 201 Created + user details
    Note over U,Email: User verifies email
    U->>API: POST /users/login (email, password)
    API->>Auth: authenticate
    Auth->>Repo: get user
    Repo-->>Auth: user found
    Auth->>Auth: verify password
    Auth-->>API: JWT token
    API-->>U: 200 OK + access token
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    users {
        UUID id PK
        UUID tenant_id
        VARCHAR email
        VARCHAR username
        VARCHAR password_hash
        VARCHAR first_name
        VARCHAR last_name
        VARCHAR phone
        VARCHAR avatar_url
        VARCHAR status
        BOOLEAN email_verified
        TIMESTAMP created
        TIMESTAMP updated
        TIMESTAMP last_login
    }

    roles {
        UUID id PK
        UUID tenant_id
        VARCHAR role_name
        TEXT description
        TIMESTAMP created
    }

    permissions {
        UUID id PK
        VARCHAR permission_name
        TEXT description
        TIMESTAMP created
    }

    user_roles {
        UUID id PK
        UUID user_id FK
        UUID role_id FK
        TIMESTAMP assigned_at
    }

    role_permissions {
        UUID id PK
        UUID role_id FK
        UUID permission_id FK
        TIMESTAMP assigned_at
    }

    users ||--o{ user_roles : "has"
    roles ||--o{ user_roles : "assigned_to"
    roles ||--o{ role_permissions : "has"
    permissions ||--o{ role_permissions : "grants"
Hold "Alt" / "Option" to enable pan & zoom

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle

Setup

git clone https://github.com/Olanna-tech/user-service-java.git
cd user-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Configuration

Set the following environment variables in application.yml: 

user:
  jwt-secret: your-secret-key
  jwt-expiration-hours: 24
  refresh-token-expiration-days: 30
  password-min-length: 8
  password-require-special-chars: true
  mfa-enabled: true
  email-verification-required: true

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact