Authentication API

Endpoints for user authentication including registration, login, logout, and user information retrieval.

The Authentication API provides endpoints for user registration, login, session management, and retrieving user information.

Endpoints

POST /api/v1/auth/register

Register a new user account.

Request Body:

JSON
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepassword123",
  "firstName": "John",
  "lastName": "Doe"
}

Response (201 Created):

JSON
{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "username": "johndoe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    "session": {
      "token": "jwt-token",
      "expiresAt": "2024-01-01T12:00:00Z"
    }
  }
}

Error Response (400 Bad Request):

JSON
{
  "success": false,
  "error": "Username, email, and password are required",
  "code": "VALIDATION_ERROR"
}

POST /api/v1/auth/login

Authenticate a user and create a session.

Request Body:

JSON
{
  "email": "john@example.com",
  "password": "securepassword123"
}

Response (200 OK):

JSON
{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "username": "johndoe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "session": {
      "token": "jwt-token",
      "expiresAt": "2024-01-01T12:00:00Z"
    }
  }
}

Error Response (400 Bad Request):

JSON
{
  "success": false,
  "error": "Email and password are required",
  "code": "VALIDATION_ERROR"
}

POST /api/v1/auth/logout

End the current user session.

Request Body: None required

Response (200 OK):

JSON
{
  "success": true,
  "message": "Logged out successfully"
}

GET /api/v1/auth/me

Retrieve information about the currently authenticated user.

Request: No body required (uses authentication token)

Response (200 OK):

JSON
{
  "success": true,
  "data": {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-01-01T00:00:00Z",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }
}

Error Response (401 Unauthorized):

JSON
{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Authentication

All endpoints except registration require valid authentication. Include the JWT token in the Authorization header:

Text
Authorization: Bearer <jwt-token>

Error Codes

CodeDescription
VALIDATION_ERRORInvalid request data
AUTH_REQUIREDAuthentication token missing or invalid
USER_EXISTSUser with this email/username already exists
INVALID_CREDENTIALSIncorrect email or password

Next Steps