Skip to content

auth-api-reference.md

Latest commit

 

History

History
229 lines (172 loc) · 4.71 KB

auth-api-reference.md

File metadata and controls

229 lines (172 loc) · 4.71 KB
Raw

Authentication API Reference

Complete API documentation for the Authentication endpoints of the PC Components Store API.

Base URL

http://localhost:8080

Authentication Overview

The API uses JWT (JSON Web Token) for authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Token Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "user@example.com",
  "role": "admin",
  "expiresAt": "2024-01-15T10:30:00Z"
}

Token Expiration: 60 minutes (configurable in appsettings.json)

Claims

The JWT token includes the following claims:

  • UserId: The user's ID (used for authorization)
  • Role: The user's role ("admin" or "customer")

Register User

POST /api/auth/register

Register a new user account.

Request Body

{
  "email": "user@example.com",
  "fullName": "John Doe",
  "password": "SecurePass123!",
  "role": "customer"
}
Field Type Required Description
email string Yes Valid email address
fullName string Yes User's full name (max 100 chars)
password string Yes Password (min requirements apply)
role string No "customer" or "admin" (default: "customer")

Success Response

HTTP/1.1 201 Created
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "user@example.com",
  "role": "customer",
  "expiresAt": "2024-01-15T10:30:00Z"
}

Error Responses

Status Code Description
400 Bad Request Invalid input or registration failed
409 Conflict Email already exists

Example Request

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "fullName": "John Doe",
    "password": "SecurePass123!",
    "role": "customer"
  }'

Login

POST /api/auth/login

Authenticate and receive a JWT token.

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}
Field Type Required Description
email string Yes Valid email address
password string Yes User's password

Success Response

HTTP/1.1 200 OK
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "user@example.com",
  "role": "customer",
  "expiresAt": "2024-01-15T10:30:00Z"
}

Error Responses

Status Code Description
401 Unauthorized Invalid credentials

Example Request

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Request/Response Models

RegisterRequest

{
  "email": "user@example.com",
  "fullName": "John Doe",
  "password": "SecurePass123!",
  "role": "customer"
}
Field Type Required Validation
email string Yes Email address format
fullName string Yes Max 100 characters
password string Yes Password requirements apply
role string No "customer" or "admin"

LoginRequest

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}
Field Type Required Validation
email string Yes Email address format
password string Yes Password

TokenResponse

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "user@example.com",
  "role": "admin",
  "expiresAt": "2024-01-15T10:30:00Z"
}
Field Type Description
token string JWT token string
email string? User's email address
role string? User's role
expiresAt DateTime Token expiration timestamp

Security Features

  • Password Hashing: BCrypt with automatic salt generation
  • JWT Authentication: Stateless token-based authentication
  • Role-Based Authorization: Admin and customer roles

Error Responses

Standard Error Format

{
  "error": "Error message description"
}

HTTP Status Codes

Code Description
200 OK Login successful
201 Created Registration successful
400 Bad Request Invalid input or validation failed
401 Unauthorized Invalid credentials
409 Conflict Email already exists