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.1

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.1
File Size Uploaded Provenance Actions
pyapiauth-0.1.1.tar.gz 10.6 kB Without provenance Details for pyapiauth-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyapiauth 0.1.1
File Interpreter ABI Platform Actions
pyapiauth-0.1.1-py3-none-any.whl Python 3 none any Details for pyapiauth-0.1.1-py3-none-any.whl

Total release size: 21.8 kB

Release files / pyapiauth-0.1.1.tar.gz

Download URL pyapiauth-0.1.1.tar.gz
Size 10.6 kB
Tags Source
SHA-256 checksum
How to use checksums
41140fb1d85155a6d59c31e5129a9fad4563d7b8f0ddfb8f1e95ac94add130bb
BLAKE2b-256 checksum
How to use checksums
40d807503997ddf3666df0115a26fb0cb5d947d24f76e8c5f76131f7cdc88d31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.1-py3-none-any.whl

Download URL pyapiauth-0.1.1-py3-none-any.whl
Size 11.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f51c447f68fcc53dd0f4ffac72f7ba80d8bf2f393188157ab8b82bc546a8e3f2
BLAKE2b-256 checksum
How to use checksums
ca291357dee1f56454a90d5356c0f9e0553e11fa63526c246be711234e254937
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.1

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.1 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