Skip to content

🖥️ 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

1
2
3
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:

1
2
3
4
5
{
  "username": "alice",
  "email": "alice@aetoskia.com",
  "is_active": true
}

The password is never returned.

🔑 Log in to get a token

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

Response 200 OK:

1
2
3
4
5
6
7
8
{
  "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:

1
2
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

1
2
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:

1
{ "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.