Authentication¶

FastPKI uses JWT (JSON Web Tokens) with OAuth2 password flow for authentication.

Login Flow¶

1. POST credentials to the token endpoint as form-encoded data.
2. Receive a JWT access token in the response.
3. Send the token as a Bearer header on every subsequent request.

Obtain a Token¶

curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -d "username=admin&password=securepassword"

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

Use the Token¶

Pass the token in the Authorization header:

curl -s http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Shell Variable Shortcut¶

TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -d "username=admin&password=securepassword" \
  | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Use in subsequent requests
curl -s http://localhost:8000/api/v1/cas/ \
  -H "Authorization: Bearer $TOKEN"

Token Lifecycle¶

FastPKI issues short-lived access tokens and long-lived refresh tokens.

Token Rotation on Refresh¶

Each call to POST /api/v1/auth/refresh consumes the submitted refresh token and issues a new access token together with a new refresh token. The old refresh token is immediately invalidated, preventing replay attacks.

Logout (Single Session)¶

POST /api/v1/auth/logout invalidates the refresh token associated with the current session and immediately revokes the caller's access token by adding it to the blocklist. Both the access token and refresh token become unusable as soon as logout completes.

Invalidate All Sessions¶

POST /api/v1/auth/invalidate invalidates all refresh tokens belonging to the authenticated user. Use this to force sign-out from every device or client at once.

Automatic Revocation¶

Refresh tokens are automatically invalidated in the following situations:

• Password change — all existing refresh tokens for the user are revoked when the password is updated.
• Account deactivation — all refresh tokens are revoked when a user's is_active flag is set to false.

Token Details¶

Token Payload¶

The JWT payload contains:

Unauthenticated Endpoints¶

The following operations can be performed without a token:

1. POST /api/v1/auth/token — login
2. POST /api/v1/users/ — create the first user (bootstrap only, by default)
3. GET /crl/{slug} and GET /ca/{slug}.crt — public PKI endpoints (CRL and CA certificate downloads)

By default, unauthenticated user registration is disabled after the first user is created. Set ALLOW_UNAUTHENTICATED_REGISTRATION=true to allow unauthenticated creation of regular user accounts. Superuser and admin accounts always require authentication.

All other API endpoints require a valid bearer token.

Failed Login Attempts¶

Failed login attempts are recorded in the audit log with action login_failure, along with the attempted username. Successful logins are recorded with login_success.