{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Aetoskia Auth Server","text":"

The Aetoskia Auth Server is the central identity service of the Aetos Platform ecosystem. It issues, validates, and introspects short-lived JWT access tokens against a single shared user store backed by MongoDB, so every service can trust one issuer instead of shipping its own auth logic.

"},{"location":"#why-centralize-authentication","title":"Why centralize authentication?","text":""},{"location":"#sections","title":"Sections","text":"Section What you'll find Centralized Auth The identity model and how the ecosystem trusts the server How to Use Register, login, and call endpoints with tokens Platform Integration How services authenticate requests Deployment Environment, Docker, and CI/CD Development Local setup, tests, and regenerating the spec"},{"location":"#endpoints-at-a-glance","title":"Endpoints at a glance","text":"Method Path Purpose POST /register Create a user account POST /login Authenticate and issue a JWT GET /me Current user (Bearer) POST /logout Stateless logout (Bearer) POST /introspect Service-to-service token verification GET /health Health check"},{"location":"#service-identity","title":"Service identity","text":""},{"location":"01_centralized_auth/","title":"Centralized Authentication","text":"

The Aetoskia Auth Server acts as the single identity provider for every application in the Aetos Platform ecosystem. The model is deliberately small and uniform.

"},{"location":"01_centralized_auth/#the-identity-model","title":"The identity model","text":"
            \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n            \u2502        Aetoskia Auth Server         \u2502\n            \u2502  users collection (MongoDB)         \u2502\n            \u2502  HS256 JWT issuer                   \u2502\n            \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                           \u2502 /login \u2192 JWT\n                           \u2502 /introspect \u2190 verification\n        \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n        \u2502                  \u2502                   \u2502\n   App A (FastAPI)    App B (service)    CLI/web clients\n   verifies via       verifies via\n   jwtlib / OpenAPI   jwtlib introspect\n   dependency\n
"},{"location":"01_centralized_auth/#token-contract","title":"Token contract","text":"

A valid access token is an HS256 JWT with exactly two claims:

{\n  \"sub\": \"alice\",\n  \"exp\": 1750000000\n}\n

There are no scopes or roles inside the token; authorization decisions belong to the consuming service, while identity and authenticity belong here.

"},{"location":"01_centralized_auth/#how-the-ecosystem-trusts-the-server","title":"How the ecosystem trusts the server","text":"
  1. Users authenticate once via /login and receive a token.
  2. Services accept that token as proof of identity after verifying it (locally via jwtlib or remotely via /introspect).
  3. Sensitive endpoints recover the user profile from the token through get_current_user or the generated dependency \u2014 never by parsing JWTs by hand.

This keeps authentication centralized while leaving each service in control of its own authorization rules.

"},{"location":"01_centralized_auth/#benefits","title":"Benefits","text":""},{"location":"02_how_to_use/","title":"How to Use","text":"

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

"},{"location":"02_how_to_use/#register-a-user","title":"Register a user","text":"
curl -X POST http://localhost:8000/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\": \"alice\", \"email\": \"alice@aetoskia.com\", \"password\": \"s3cret!\"}'\n

Response 201 Created:

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

The password is never returned.

"},{"location":"02_how_to_use/#log-in-to-get-a-token","title":"Log in to get a token","text":"
curl -X POST http://localhost:8000/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\": \"alice\", \"password\": \"s3cret!\"}'\n

Response 200 OK:

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

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

"},{"location":"02_how_to_use/#call-a-protected-endpoint","title":"Call a protected endpoint","text":"

Send the token as a bearer token:

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

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

"},{"location":"02_how_to_use/#log-out","title":"Log out","text":"
curl -X POST http://localhost:8000/logout \\\n  -H \"Authorization: Bearer <jwt>\"\n

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

{ \"message\": \"Successfully logged out. Please discard your token on the client.\" }\n
"},{"location":"02_how_to_use/#token-lifecycle-quick-reference","title":"Token lifecycle quick reference","text":"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.

"},{"location":"03_platform_integration/","title":"Platform Integration","text":"

This page is for service authors wiring authentication into Aetos applications. It covers both supported integration paths.

"},{"location":"03_platform_integration/#path-1-jwtlib-client-py-jwt","title":"Path 1: jwtlib client (py-jwt)","text":"

Services that depend on the py-jwt library can authenticate requests without an OpenAPI generator. Set the auth server base URL:

export JWT_SERVER=http://auth.aetoskia.com\n

Then verify incoming requests:

from jwtlib.introspection import authenticate_request\n\nauthorized = await authenticate_request(\n    should_skip_authentication,  # e.g. allow public paths\n    method,\n    path,\n    authorization_token,         # \"Bearer <jwt>\" or None\n)\n

authenticate_request POSTs {\"token\": \"<jwt>\"} to {JWT_SERVER}/introspect (3 second timeout) and treats {\"active\": true, \"user\": {...}} as valid. Transport errors surface as AuthServiceUnavailable.

For zero-request validation (offline token decode), jwtlib also exposes the token payload helpers used by the auth server itself \u2014 see the py-jwt documentation.

"},{"location":"03_platform_integration/#path-2-openapi-first-generated-dependencies","title":"Path 2: openapi-first generated dependencies","text":"

Services declared with an OpenAPI-first contract can generate their FastAPI dependencies from the spec. Declare a bearer security scheme pointing at the auth server:

securitySchemes:\n  HTTPBearer:\n    type: http\n    scheme: bearer\n    x-server-url: https://auth.aetoskia.com\n    x-introspect-path: /introspect\n

The generated dependency then POSTs {\"token\": token} to the introspection path and returns the user on active == true, raising 401 on invalid or inactive tokens and 503 when the auth server is unreachable.

"},{"location":"03_platform_integration/#the-introspect-contract","title":"The /introspect contract","text":"Field Type Description request token (string) The JWT to verify response active (bool) Whether the token is valid and active response user (PublicUser | null) The profile when active

The endpoint always answers 200 \u2014 validity is expressed through active. IntrospectResponse never raises, so the caller can act on the tri-state (valid / invalid / user missing) without exception handling.

"},{"location":"03_platform_integration/#protecting-endpoints-in-fastapi","title":"Protecting endpoints in FastAPI","text":"

For first-party services, mount the auth router's dependency directly:

from fastapi import Depends\nfrom jwtlib import PublicUser\nfrom jwt import get_current_user\n\n@app.get(\"/profile\")\nasync def profile(current_user: PublicUser = Depends(get_current_user)):\n    return current_user\n
"},{"location":"03_platform_integration/#golden-rules","title":"Golden rules","text":"
  1. Never trust an unverified token \u2014 always decode through jwtlib or introspect before handling the request.
  2. Treat active: false as unauthenticated, even if the JWT decodes.
  3. Do not implement your own JWT parsing \u2014 use a generated dependency or the jwtlib client so revocation and issuer changes stay centralized.
"},{"location":"04_deployment/","title":"Deployment","text":"

How the auth server is configured and shipped.

"},{"location":"04_deployment/#environment-variables","title":"Environment variables","text":"Variable Required Default Purpose MONGO_HOST yes \u2014 MongoDB host MONGO_USER no \u2014 MongoDB username MONGO_PASS no \u2014 MongoDB password MONGO_PORT no 27017 MongoDB port MONGO_DB_NAME no auth Database name JWT_SECRET no* superstrongsecretkey Token signing secret (*set in production!)

Credentials and the token secret live in the environment / Deploy secrets \u2014 see .env.example for the shape. .env is gitignored.

"},{"location":"04_deployment/#running-locally","title":"Running locally","text":"
cp .env.example .env      # fill in MONGO_HOST, JWT_SECRET\nuvicorn main:app --reload --port 8000\n

The health endpoint is available at GET /health.

"},{"location":"04_deployment/#container-image","title":"Container image","text":"

The Dockerfile is a multi-stage build on python:3.13-slim:

  1. Builder installs requirements.txt from the private pip index using build args PIP_USERNAME, PIP_PASSWORD, PIP_REPO_URL.
  2. Runtime copies Python 3.13 from the builder, installs curl, exposes port 8000, and runs uvicorn main:app. A HEALTHCHECK curls /health.
"},{"location":"04_deployment/#cicd-drone","title":"CI/CD (Drone)","text":"

.drone.yml ships on git tag events (arm64):

  1. Resolve the latest tag.
  2. Skip if the image already exists.
  3. docker build with pip credentials (secrets) \u2192 aetos/auth-server:$TAG and :latest.
  4. Push to $REGISTRY_HOST/aetos/auth-server:*.
  5. Restart the running container auth-server.

The deployed container runs with --restart always, maps host 9003 \u2192 8000, resolves private-pi to 192.168.1.111 for Mongo, and receives MONGO_* + JWT_SECRET from secrets.

"},{"location":"04_deployment/#environments","title":"Environments","text":"Environment Base URL Production https://auth.aetoskia.com Internal staging http://server-pi:9002 Local development http://localhost:8000"},{"location":"05_development/","title":"Development","text":"

Working on the auth server itself.

"},{"location":"05_development/#repository-layout","title":"Repository layout","text":"Path Purpose main.py FastAPI app factory, environment wiring, lifespan, OpenAPI customization jwt/ The auth routes package (router, get_current_user) generate_spec.py Regenerates the committed OpenAPI spec docs/api/ API reference (Swagger UI embed + openapi.json) docs/lib/ Generated library reference (docforge) docs/wiki/ This hand-written wiki tests/ Async route tests against an in-memory Mongo mock"},{"location":"05_development/#setup","title":"Setup","text":"
python -m venv .venv\n.venv/Scripts/pip install -r requirements.txt\n

Dependencies are installed from the private pip index (see requirements.txt and the Dockerfile). Core runtime packages:

"},{"location":"05_development/#tests","title":"Tests","text":"

Run the suite (no network or Mongo required \u2014 an in-memory mock is used):

.venv/Scripts/pytest --asyncio-mode=auto\n

Coverage spans the full HTTP flow: register \u2192 login \u2192 wrong-password 401 \u2192 /me with and without a token \u2192 stateless logout.

"},{"location":"05_development/#regenerating-the-openapi-spec","title":"Regenerating the OpenAPI spec","text":"

The committed docs/api/openapi.json is produced offline:

set MONGO_HOST=127.0.0.1\npython generate_spec.py\n

MONGO_HOST only needs to be set for the import; no connection is opened.

"},{"location":"05_development/#building-documentation-docforge","title":"Building documentation (docforge)","text":"

The site is generated by docforge and served per kind under site/{kind}:

doc-forge build \\\n  --api --openapi-spec docs/api/openapi.json \\\n  --mkdocs --wiki \\\n  --module-is-source --module jwt \\\n  --site-name \"Aetoskia Auth Server\"\n

Preview locally:

doc-forge serve --api\ndoc-forge serve --lib\ndoc-forge serve --wiki\n
"}]}