OAuth API Reference

The OAuth proxy lives in oauth/app.py and handles the GitHub OAuth handshake for Decap CMS. Three routes, one module, no database.

When running locally (make oauth-serve), Litestar auto-generates interactive API docs at http://localhost:8000/api via the Scalar UI plugin. In production, the same docs are at api.wiki.python.org/api.

Endpoints

Method

Path

What it does

GET

/auth

Redirects the user to GitHub’s OAuth authorize page

GET

/callback?code=...

Exchanges the authorization code for a token, posts it back to the CMS via postMessage

GET

/_health/

Returns {"status": "ok"} for load balancers

Module reference

GitHub OAuth proxy for Decap CMS.

async app.auth(provider: str = 'github', site_id: str = '') → Redirect[source]

Redirect the user to GitHub’s OAuth authorization page.

Decap CMS hits this endpoint to start the OAuth flow. The user gets sent to GitHub to approve access, then GitHub redirects back to callback() with an authorization code.

A random state is generated, stored in a short-lived http-only cookie, and sent to GitHub; callback() verifies the echoed state against the cookie to defend against OAuth CSRF / code injection. The requested scope is fixed server-side (OAUTH_SCOPE) and cannot be influenced by the caller.

Parameters:

  • provider – OAuth provider name (passed by Decap CMS, always github).

  • site_id – Site identifier (passed by Decap CMS, unused).

async app.callback(code: str, state_param: Annotated[str, ~litestar.params.ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=<_EmptyEnum.EMPTY: 0>, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, include_in_schema=True, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query=state, required=None)] = '', state_cookie: Annotated[str, ~litestar.params.ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=<_EmptyEnum.EMPTY: 0>, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, include_in_schema=True, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=oauth_state, query=None, required=None)] = '') → ASGIResponse[source]

Exchange a GitHub authorization code for an access token.

GitHub redirects here after the user approves the OAuth request. The proxy first verifies the state echoed by GitHub against the cookie set in auth() (CSRF protection), then exchanges the temporary code for an access token and returns a small HTML page that postMessage’s the token back to the CMS window – only to an allowlisted origin.

The parameters are deliberately not named state/scope: those are Litestar reserved keywords and would be injected with framework objects instead of the request values.

Parameters:

  • code – The authorization code from GitHub’s OAuth redirect.

  • state_param – The state value echoed back by GitHub (state query key).

  • state_cookie – The state value stored by auth() (cookie).

async app.health() → dict[str, str][source]

Health check endpoint for load balancers and uptime monitors.

Returns {"status": "ok"} when the service is running.