How to Use

This page covers the plain HTTP usage of the auth server: creating users, logging in, and calling protected endpoints with a bearer token.

Register a user

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "email": "alice@aetoskia.com", "password": "s3cret!"}'

• username — 3 to 50 characters (required).
• email — valid email (optional).
• password — at least 6 characters (required; stored hashed).

Response 201 Created:

{
  "username": "alice",
  "email": "alice@aetoskia.com",
  "is_active": true
}

The password is never returned.

Log in to get a token

curl -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "s3cret!"}'

Response 200 OK:

{
  "access_token": "<jwt>",
  "user": {
    "username": "alice",
    "email": "alice@aetoskia.com",
    "is_active": true
  }
}

Invalid credentials return 401 with {"detail": "Invalid credentials"}.

Call a protected endpoint

Send the token as a bearer token:

curl http://localhost:8000/me \
  -H "Authorization: Bearer <jwt>"

Response 200 OK with the current user profile. A missing or invalid token returns 401 with WWW-Authenticate: Bearer.

Log out

curl -X POST http://localhost:8000/logout \
  -H "Authorization: Bearer <jwt>"

Logout is stateless — the server returns a confirmation and the client must discard the token:

{ "message": "Successfully logged out. Please discard your token on the client." }

Token lifecycle quick reference

Event	Endpoint	Result
Create identity	POST /register	user profile
Obtain token	POST /login	access_token + user
Verify (self)	GET /me	user profile or 401
End session	POST /logout	discard-token confirmation
Verify (other services)	POST /introspect	active + user

Interactive examples are available in the API Reference site (Swagger UI), rendered from docs/api/openapi.json.

---