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(scope: str = 'public_repo', provider: str = 'github', site_id: str = '') → Redirect

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.

Parameters:

• scope – GitHub OAuth scope to request. Defaults to public_repo.

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

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

async app.callback(code: str) → ASGIResponse

Exchange a GitHub authorization code for an access token.

GitHub redirects here after the user approves the OAuth request. The proxy exchanges the temporary code for a long-lived access token, then returns a small HTML page that postMessage’s the token back to the Decap CMS window.

Parameters:

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

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

Health check endpoint for load balancers and uptime monitors.

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