ILD Auth API Documentation

The ILD Auth service provides endpoints for user authentication, profile management, and user administration. The API is divided into three main sections: Public, Private, and Admin endpoints.

Public Endpoints

These endpoints are accessible without authentication, except where noted.

Authentication

Login

• Endpoint: POST /sign/login
• Description: Authenticates a user and returns a JWT token
• Request Body: json { "email": "string", "password": "string" }
• Response: JWT token and user information
• Status Codes:
• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Register

• Endpoint: POST /sign/register
• Description: Creates a new user account
• Request Body: json { "email": "string", "password": "string", "firstName": "string", "lastName": "string" }
• Response: Created user object
• Status Codes:
• 201: Created
• 400: Bad Request
• 500: Internal Server Error

Check Authentication

• Endpoint: GET /sign/check
• Description: Verifies if the current session is valid
• Response: Authentication status
• Status Codes:
• 200: Success
• 401: Unauthorized

Refresh Token

• Endpoint: GET /sign/refresh
• Description: Refreshes the JWT token
• Response: New JWT token
• Status Codes:
• 200: Success
• 401: Unauthorized

Logout

• Endpoint: GET /sign/logout
• Description: Logs out the current user
• Authentication: Required
• Status Codes:
• 200: Success
• 401: Unauthorized

Verify Email

• Endpoint: POST /sign/verify
• Description: Verifies user's email address
• Request Body: json { "token": "string" }
• Status Codes:
• 200: Success
• 400: Bad Request
• 500: Internal Server Error

Reset Password

• Endpoint: POST /sign/reset
• Description: Initiates password reset process
• Request Body: json { "email": "string" }
• Status Codes:
• 200: Success
• 400: Bad Request
• 500: Internal Server Error

Reset Password with Token

• Endpoint: POST /sign/reset/:token
• Description: Completes password reset process
• Parameters:
• token (path): Reset token
• Request Body: json { "password": "string" }
• Status Codes:
• 200: Success
• 400: Bad Request
• 500: Internal Server Error

User Profile

Get Public User Profile

• Endpoint: GET /user/profile/:userId
• Description: Retrieves public profile information for a user
• Parameters:
• userId (path): User identifier
• Response: Public user profile object
• Status Codes:
• 200: Success
• 404: User not found
• 500: Internal Server Error

Private Endpoints

These endpoints require authentication.

User Profile

Get User Profile

• Endpoint: GET /user/profile
• Description: Retrieves the authenticated user's profile
• Authentication: Required
• Response: User profile object
• Status Codes:
• 200: Success
• 401: Unauthorized
• 500: Internal Server Error

Update User Profile

• Endpoint: PUT /user/profile
• Description: Updates the authenticated user's profile
• Authentication: Required
• Request Body: Multipart form data
• profileImage (file): Profile image
• Other profile fields
• Response: Updated user profile object
• Status Codes:
• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Stream Profile Image

• Endpoint: GET /user/profile/stream/:key
• Description: Streams a user's profile image
• Authentication: Required
• Parameters:
• key (path): Image key
• Response: Image stream
• Status Codes:
• 200: Success
• 401: Unauthorized
• 404: Image not found

User Management

Change Password

• Endpoint: PUT /user/changepassword
• Description: Changes the authenticated user's password
• Authentication: Required
• Request Body: json { "currentPassword": "string", "newPassword": "string" }
• Status Codes:
• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Finish Tutorial

• Endpoint: PUT /user/tutorial
• Description: Marks the user's tutorial as completed
• Authentication: Required
• Status Codes:
• 200: Success
• 401: Unauthorized
• 500: Internal Server Error

Join Community

• Endpoint: PATCH /user/community/join/:communityId
• Description: Adds user to a community
• Authentication: Required
• Parameters:
• communityId (path): Community identifier
• Status Codes:
• 200: Success
• 401: Unauthorized
• 404: Community not found
• 500: Internal Server Error

Admin Endpoints

These endpoints require admin authentication.

User Management

Get All Users

• Endpoint: GET /user
• Description: Retrieves all users
• Authentication: Required (Admin)
• Response: Array of user objects
• Status Codes:
• 200: Success
• 401: Unauthorized
• 403: Forbidden
• 500: Internal Server Error

Get User by ID

• Endpoint: GET /user/:userId
• Description: Retrieves a specific user by ID
• Authentication: Required (Admin)
• Parameters:
• userId (path): User identifier
• Response: User object
• Status Codes:
• 200: Success
• 401: Unauthorized
• 403: Forbidden
• 404: User not found
• 500: Internal Server Error

Index User Categories

• Endpoint: PATCH /user/:userId/index
• Description: Reindexes user categories
• Authentication: Required (Admin)
• Parameters:
• userId (path): User identifier
• Status Codes:
• 200: Success
• 401: Unauthorized
• 403: Forbidden
• 404: User not found
• 500: Internal Server Error

Recalculate User Subscription

• Endpoint: PUT /user/:userId/recalculate-subscription
• Description: Recalculates user's subscription status
• Authentication: Required (Admin)
• Parameters:
• userId (path): User identifier
• Status Codes:
• 200: Success
• 401: Unauthorized
• 403: Forbidden
• 404: User not found
• 500: Internal Server Error

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "string",
  "message": "string"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}