pyapiauth
Verify an OIDC provider's RFC 9068 access tokens inside a Python web API. A CLI logs in with the device grant, a service with the client-credentials grant, and each sends the provider's access token as a bearer. pyapiauth checks it against the issuer's published keys and says who is asking: a person, or a service client limited to its scopes.
It is the Python sibling of goapiauth. Its client-side counterpart is pyclilogin, which obtains the tokens this package verifies.
Install
uv add pyapiauth # the verifier
uv add "pyapiauth[fastapi]" # plus the FastAPI dependencies
Starting from scratch
An API for a product called acme trusts one issuer and two client prefixes:
acme-cli- for each person's machine, and acme-svc- for each service.
from fastapi import APIRouter, Depends
from pyapiauth import LazyVerifier, person_prefix, service_prefix
from pyapiauth.fastapi_dependencies import person_dependency, person_or_scoped_service_dependency
verifier = LazyVerifier('https://auth.example.com', person_prefix('acme'), service_prefix=service_prefix('acme'))
people = APIRouter(dependencies=[Depends(person_dependency(verifier))])
readers = APIRouter(dependencies=[Depends(person_or_scoped_service_dependency(verifier, 'acme.read'))])
Each dependency puts the verified Caller on request.state.caller. Without
FastAPI, verifier.verify(token) returns the Caller or raises.
LazyVerifier reads the issuer's discovery document on the first request,
rather than at startup. An issuer that is down then cannot stop the API from
starting, and a failed read is tried again on the next request.
A token passes six checks, in this order
- The header's
typisat+jwt. - The signature verifies against a key from the issuer's JWKS.
issis the issuer the API trusts.client_idstarts with the person prefix or the service prefix.expis in the future.- A person's token carries a
sub. A service's token carries a non-emptyscp.
The type check comes first because an id_token from the same issuer is signed
by the same key, and would otherwise pass every later step. The prefix decides
whether a token is a person's or a service's, never the absence of sub. The
audience claim is not checked, because some providers leave it empty on a
device grant's token. The client prefix keeps another product's tokens out.
A prefix no product name builds is refused when the verifier is built. A bare
acme would admit acmecorp-cli-desk. An empty service prefix refuses every
service token.
A refusal tells the caller nothing, and an outage is not a refusal
| Outcome | Exception | FastAPI answer |
|---|---|---|
| No bearer, or one that fails a check | Rejected |
401 Invalid credentials, with a WWW-Authenticate challenge |
| The issuer cannot be read | IssuerUnreachable |
503 Identity provider unavailable |
| A service on a route no scope of its admits | — | 403 |
A caller probing with forged tokens learns nothing about which check failed.
The reason goes to the pyapiauth.fastapi_dependencies logger, as
bearer_rejected at WARNING, issuer_unreachable at ERROR, and
bearer_missing and service_refused at INFO. A 503 never sends anyone to log
in again, because a login cannot fix a network fault.
The keys outlive an outage of the issuer
HeldKeys reads the key set once and holds it. A token naming a kid no held
key carries reads it again, which finds a key the provider has just rotated in.
Those reads are at least 30 seconds apart, so a stream of forged tokens costs
the provider one read per gap. Keys older than five minutes are read again too,
which bounds how long a key the provider stopped publishing still verifies. A
read that fails keeps the held keys, so an outage of the issuer is not an
outage of the API.
What it deliberately does not do
It does not issue, refresh or store tokens; pyclilogin does that on the client. It verifies RS256 alone, and does not introspect opaque tokens.
Metadata
Release files for pyapiauth 0.1.0
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 |
|---|---|---|---|---|
| pyapiauth-0.1.0.tar.gz | 10.6 kB | Without provenance | Details for pyapiauth-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyapiauth-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pyapiauth-0.1.0-py3-none-any.whl |
Total release size: 21.8 kB
Release files / pyapiauth-0.1.0.tar.gz
| Download URL | pyapiauth-0.1.0.tar.gz |
|---|---|
| Size | 10.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4cc93bf401b1675dc711c3c58ed50b6b51707438acf44ab5490506a448ac976b
|
|
BLAKE2b-256 checksum How to use checksums |
44a1ab71e52d54aa58277432c4403e6362ee692146b249e24db80cf195628d2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / pyapiauth-0.1.0-py3-none-any.whl
| Download URL | pyapiauth-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f9ca16ced73f4f9d9aeee80147df8a994b6353793aba55623809dbe4677bf85
|
|
BLAKE2b-256 checksum How to use checksums |
c68ca356d5e394fe8ccf81218a0e5fb939215bfc4a990eb1e8af77ceeecfbde2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for pyapiauth 0.1.0
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.