litestar-oauth-server
An OAuth 2.1 authorization server plugin for Litestar: PKCE, client registration, token and refresh, with MCP-ready metadata
Install
pip install litestar-oauth-server
Requires Python 3.12+.
Quickstart
from litestar import Litestar, Request, get
from litestar_oauth_server import (
AuthorizationServer, LitestarOAuth, OAuthConfig, bearer_guard, in_memory_stores, verified_token,
)
RESOURCE = "https://api.example.com/mcp"
server = AuthorizationServer(
config=OAuthConfig(
issuer="https://api.example.com",
authorization_endpoint="https://app.example.com/oauth/authorize", # your consent page
resources=(RESOURCE,),
scopes_supported=("things:read", "things:write"),
),
stores=in_memory_stores(), # use stores on your own database in production
)
@get("/mcp", guards=[bearer_guard(server, RESOURCE, scope="things:read")])
async def things(request: Request) -> str:
token = verified_token(request) # subject, binding, scopes
return f"hello {token.subject}, pinned to {token.binding}"
app = Litestar([things], plugins=[LitestarOAuth(server)])
Your consent page signs the user in with your own login, then calls
server.approve(request, Approval(subject=..., scopes=..., binding=...)) and sends the browser to
the URL it returns. See examples/basic.py.
Why litestar-oauth-server
Adding "Connect to Claude", a CLI login or a third-party integration to a Litestar API needs an OAuth 2.1 authorization server: PKCE, client registration, token and refresh, discovery documents. This library provides that part and leaves the login, the consent screen and the database to your app. It is the server side an MCP connector needs, and it works the same for any other client.
Key features
- Authorization code flow with PKCE (S256 only), public clients, refresh token rotation.
- Server metadata (RFC 8414), protected resource metadata (RFC 9728), dynamic client registration (RFC 7591), revocation (RFC 7009), resource indicators (RFC 8707).
- A
bindingon every token: the tenant chosen on the consent screen. The token never crosses it. - Narrow scopes: the user approves a subset of what the client asked for (read-only first).
- Code and refresh token are single use; a reused refresh token revokes its whole family.
- A bearer guard that answers 401 with
WWW-Authenticate: Bearer resource_metadata=.... - Frozen dataclasses throughout; storage is three small protocols you implement on your database.
Links
- Documentation: https://cardona-oss.gitlab.io/litestar-oauth-server/
- Source: https://gitlab.com/cardona-oss/litestar-oauth-server
- Issues: https://gitlab.com/cardona-oss/litestar-oauth-server/-/issues
- PyPI: https://pypi.org/project/litestar-oauth-server/
- Changelog: CHANGELOG.md
Contributing
Developer setup, the dev loop, and the release process live in
CONTRIBUTING.md. In short: uv sync && make install-hooks, then
make check runs the same gate CI runs.
License
MIT © 2026 Jorge Cardona (see LICENSE).
Metadata
Release files for litestar-oauth-server 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| litestar_oauth_server-0.0.3.tar.gz | 18.6 kB | Without provenance | Details for litestar_oauth_server-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| litestar_oauth_server-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for litestar_oauth_server-0.0.3-py3-none-any.whl |
Total release size: 34.3 kB
Release files / litestar_oauth_server-0.0.3.tar.gz
| Download URL | litestar_oauth_server-0.0.3.tar.gz |
|---|---|
| Size | 18.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b61f77a0647a5c783841772b75f5fe939d091cb5faf4dd8806a3bb143f37e9d9
|
|
BLAKE2b-256 checksum How to use checksums |
72ae21dbfa2ca4a6e5d55a0e50698b42535cf178e1f036687237eb397c6cb7c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / litestar_oauth_server-0.0.3-py3-none-any.whl
| Download URL | litestar_oauth_server-0.0.3-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
85c475a80a985fb990dd68abdbe9292fcd95909f60add7637adf2599ecf4b1f4
|
|
BLAKE2b-256 checksum How to use checksums |
71f6f9036308d42917f789c832918e1bd7f75fe3d85c65adbace569c23060690
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for litestar-oauth-server 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.