Skip to main content

Authentication API

Endpoints for user authentication, registration, and session management.

Create Guest Account​

Create a guest account for anonymous browsing.

POST /auth/guest

Authentication​

None required

Request Body​

{}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "guest_1234567890",
    "email": null,
    "displayName": "Guest",
    "avatarUrl": null,
    "tier": "free",
    "isGuest": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors​

  • 500 InternalServerError - Server error creating guest account

Sign Up​

Register a new user account.

POST /auth/signup

Authentication​

None required

Request Body​

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecureP@ssw0rd",
  "displayName": "John Doe"
}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john@example.com",
    "displayName": "John Doe",
    "avatarUrl": null,
    "tier": "free",
    "isGuest": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors​

  • 400 ValidationError - Invalid request body (missing fields, invalid format)
  • 409 Conflict - Username or email already exists
  • 500 InternalServerError - Server error

Example​

curl -X POST https://api.bookwish.app/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "SecureP@ssw0rd",
    "displayName": "John Doe"
  }'

Login​

Authenticate an existing user.

POST /auth/login

Authentication​

None required

Request Body​

{
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john@example.com",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
    "tier": "premium",
    "isGuest": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors​

  • 400 ValidationError - Invalid request body
  • 401 Unauthorized - Invalid credentials
  • 500 InternalServerError - Server error

Example​

curl -X POST https://api.bookwish.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecureP@ssw0rd"
  }'

Refresh Token​

Refresh an expired access token using a refresh token.

POST /auth/refresh

Authentication​

None required

Request Body​

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Errors​

  • 400 ValidationError - Missing refresh token
  • 401 Unauthorized - Invalid or expired refresh token
  • 500 InternalServerError - Server error

Example​

curl -X POST https://api.bookwish.app/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Migrate Guest​

Convert a guest account to a full user account.

POST /auth/migrate-guest

Authentication​

Required (Bearer token)

Request Body​

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecureP@ssw0rd",
  "displayName": "John Doe"
}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john@example.com",
    "displayName": "John Doe",
    "avatarUrl": null,
    "tier": "free",
    "isGuest": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors​

  • 400 ValidationError - Invalid request body
  • 401 Unauthorized - Not authenticated or not a guest account
  • 409 Conflict - Username or email already exists
  • 500 InternalServerError - Server error

Example​

curl -X POST https://api.bookwish.app/auth/migrate-guest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "SecureP@ssw0rd",
    "displayName": "John Doe"
  }'

Logout​

Invalidate current session and refresh token.

POST /auth/logout

Authentication​

Required (Bearer token)

Request Body​

{}

Response​

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

Errors​

  • 401 Unauthorized - Not authenticated
  • 500 InternalServerError - Server error

Example​

curl -X POST https://api.bookwish.app/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

Token Usage​

All authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Access tokens expire after 24 hours. Use the refresh token endpoint to obtain a new access token without requiring the user to log in again.