Skip to main content

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

  1. The header's typ is at+jwt.
  2. The signature verifies against a key from the issuer's JWKS.
  3. iss is the issuer the API trusts.
  4. client_id starts with the person prefix or the service prefix.
  5. exp is in the future.
  6. A person's token carries a sub. A service's token carries a non-empty scp.

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)

Source distribution for pyapiauth 0.1.0
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)

Table of built distributions (wheels) for pyapiauth 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page