API reference

The package’s public imports are GitHub, Config and Token:

import flask_githubkit

github = flask_githubkit.GitHub()

Most applications only need GitHub. The extension handles callback state validation, code exchange and token persistence. Application code uses github.client() to make GitHub API calls.

GitHub

The generated reference below documents the public extension methods and their signatures.

class flask_githubkit.GitHub(app: Flask | None = None, *, scope: str | None = None, login_view: str | None = None)

GitHub OAuth web flow for Flask, backed by GitHubKit.

login starts the flow and callback wraps the callback view, passing it the access token (or None if the user denied access). client returns one GitHub client per request for the signed-in user. init_app sends users to the endpoint named by GITHUB_LOGIN_VIEW (default login) when their refresh token has expired.

scope and login_view may be given here. When they are not, they come from GITHUB_SCOPE and GITHUB_LOGIN_VIEW in the Flask config. The scope then defaults to read:user. The login view defaults to the view decorated with @login, or to login if there is none. Tokens are kept by store.Token in flask.session.

callback(view_func: Callable[[...], Response | tuple[Response, int]]) → Callable[[...], Response | tuple[Response, int]]

Wrap the callback view.

The wrapper checks the OAuth state, exchanges the code and saves the token. It then calls the view with the access token, or with None if the user denied access.

client() → GitHub[Any] | None

Return the request’s GitHub client, or None if signed out.

The client is created once per request, so a token refresh happens once and every caller sees the new token. GitHubKit refreshes an expired access token itself; the refreshed values are saved to the session at the end of the request.

init_app(app: Flask) → None

Register the AuthExpiredError handler on app.

login() → Response | tuple[Response, int]

login(view_func: Callable[[...], Any]) → Callable[[...], Response | tuple[Response, int]]

Start the OAuth flow.

Call login() inside a view, or use @github.login as a decorator. The decorated function is replaced by one that redirects to GitHub, and keeps its name for url_for.

logout() → None

Remove the stored token and any cached client.

Callback behavior

@github.callback checks and consumes the one-time OAuth state value before calling the decorated view. Invalid or replayed state returns HTTP 400 and the view is not called. If the user denies authorization, the view receives None. When the exchange succeeds, the view receives the access token as its first argument.

If GitHub redirects back without an authorization code, the extension returns HTTP 400. Network failures while exchanging the code return HTTP 502. If the GitHubKit client later raises AuthExpiredError, the extension clears the token and redirects to the configured or discovered login endpoint.

Config

Config.from_current_app() reads the OAuth client ID, client secret, redirect URI, scope and Flask SECRET_KEY from the active Flask app. It returns None when required configuration is missing or invalid. Most applications do not need to construct or call Config directly.

Token

Token serializes and restores the GitHubKit OAuth token strategy in flask.session. Application code normally uses GitHub.callback, GitHub.client() and GitHub.logout() instead of calling Token directly.

For GitHubKit’s complete API, see its REST API documentation.