Authentication#

Overdue uses JWT tokens ("library cards") for authentication. All write operations require a valid library card.

Overview#

Library cards are issued when a librarian logs in and expire after 1 hour (60 minutes). Include the token in the Authorization header as a Bearer token.

Registration#

Create a new librarian account:

curl -X POST http://localhost:8000/api/librarians/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ada",
    "email": "ada@example.com",
    "password": "lovelace1815"
  }'

Requirements:

• Username: 3-100 characters, unique
• Email: valid email format, unique
• Password: minimum 8 characters

Login#

Obtain a library card:

curl -X POST http://localhost:8000/api/librarians/login \
  -H "Content-Type: application/json" \
  -d '{"username": "ada", "password": "lovelace1815"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Using your library card#

Include the token in the Authorization header:

curl -X POST http://localhost:8000/api/volumes/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"title": "My Volume", "content": "...", "shelf_id": 1}'

Token details#

• Algorithm: HS256
• Expiry: 60 minutes (configurable via OVERDUE_TOKEN_EXPIRY_MINUTES)
• Payload: librarian ID, username, role

Refreshing your library card#

Library cards can be refreshed before they expire:

curl -X POST http://localhost:8000/api/librarians/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

This returns a new library card with a fresh expiry.

Roles and permissions#

Overdue uses a rank-based permission system. See the gameplay guide for rank details.

Error responses#

• 401: "You'll need a library card to access the stacks." (missing or invalid token)
• 401: "Your library card has expired. Renew at POST /librarians/login." (expired token)
• 403: "Only the head librarian has access to the restricted section." (insufficient role)