Stateless OAuth 2.0 protocol library with PKCE, token refresh, and provider-specific revocation.
Provider-specific OAuth knowledge — endpoints, auth methods, PKCE quirks, error classification, and revocation — encoded as a library so your application doesn't have to maintain it.
| What | Why |
|---|---|
| Provider presets | Endpoints, auth methods, PKCE toggles, scope separators, and revocation for multiple providers out of the box. |
| Error classification | Distinguishes permanent failures (revoked token, invalid client) from transient ones so callers know whether to retry or re-authenticate. |
| Revocation support | Providers all revoke differently (POST, DELETE, GET, Basic auth, query params) — presets include the right handler when available. |
| Auth method handling | client_secret_post vs client_secret_basic — picked from your config and handled by authlib under the hood. |
| PKCE (S256) | Generated automatically when the provider supports it, no setup needed. |
apron-auth is stateless. It doesn't store tokens, manage sessions, or hold database connections — you bring your own storage, apron-auth handles the protocol.
# via uv
uv add apron-auth
# via pip
pip install apron-authRequires Python 3.11+.
Presets bundle the endpoints, auth method, PKCE config, and revocation handler for a given provider into a single call.
from apron_auth.providers import google
config, revocation_handler = google.preset(
client_id="your-client-id",
client_secret="your-client-secret", # pragma: allowlist secret
scopes=["openid", "email", "profile"],
)If you use apron-tools, scopes come from capability groups instead of being hardcoded:
from apron_tools.providers.google.gmail.scopes import CAPABILITY_GROUP as GMAIL
config, revocation_handler = google.preset(
client_id="your-client-id",
client_secret="your-client-secret", # pragma: allowlist secret
scopes=GMAIL.scopes,
)If your provider doesn't have a preset, configure it directly.
from pydantic import SecretStr
from apron_auth import ProviderConfig
config = ProviderConfig(
client_id="your-client-id",
client_secret=SecretStr("your-client-secret"), # pragma: allowlist secret
authorize_url="https://provider.com/oauth/authorize",
token_url="https://provider.com/oauth/token",
scopes=["read", "write"],
)Build the URL to redirect the user to. State and PKCE are included automatically.
from apron_auth import OAuthClient
client = OAuthClient(config)
url, pending_state = await client.get_authorization_url(
redirect_uri="https://yourapp.com/callback",
)
# Redirect the user to `url`.
# Hold onto `pending_state` — you'll need it for the callback.When the user comes back with an authorization code, exchange it for tokens.
tokens = await client.exchange_code(
code="authorization-code-from-callback",
redirect_uri="https://yourapp.com/callback",
code_verifier=pending_state.code_verifier,
)
print(tokens.access_token)
print(tokens.refresh_token)If you need normalized identity fields for login or account-linking flows, fetch them after token exchange:
tokens = await client.exchange_code(
code="authorization-code-from-callback",
redirect_uri="https://yourapp.com/callback",
code_verifier=pending_state.code_verifier,
)
identity = await client.fetch_identity(tokens)
print(identity.provider) # "google", "github", etc.
print(identity.email)
print(identity.email_verified)fetch_identity takes the TokenSet from exchange_code (or
refresh_token). It is narrowed to an IdentityMaterial — exposing
only the access token and, for OIDC providers, the ID token — before
being handed to the provider's identity handler, so handlers never
receive the refresh token or caller context.
Built-in identity handlers are inferred from standard Google, GitHub,
HubSpot, Microsoft, Atlassian, Typeform, Salesforce, Notion, and Linear
endpoint hostnames, so they apply to both the bundled preset(...)
configs and any manually constructed ProviderConfig pointing at those
hosts. For other providers, pass a custom identity_handler to
OAuthClient.
OAuth protocol endpoints come from the provider config; identity API
endpoints are provider-specific internals handled by the identity
handler.
Typeform's /me response does not include a stable, opaque user
identifier, so IdentityProfile.subject is always None for that
provider. The available alternatives are IdentityProfile.email
(stable but PII) and IdentityProfile.username (the Typeform
alias, which is user-mutable); callers that need a non-PII stable
handle must derive one themselves, for example by hashing
email.
Notion's /v1/users/me returns a bot user object. For external (public
OAuth) integrations where bot.owner.type == "user", fetch_identity
maps owner user fields into IdentityProfile. For internal
workspace-owned integrations where bot.owner.type == "workspace",
Notion does not expose end-user email, so IdentityProfile.email is
None by design.
HubSpot's fetch_identity calls the access-token introspection
endpoint, which mixes user and portal/account identity in one
response. IdentityProfile.subject and IdentityProfile.email map to
the HubSpot user (user_id and user); the portal (hub_id,
hub_domain) populates IdentityProfile.tenancies (see "Tenancy"
below). The full response — including app_id, scopes, and
expires_in — is preserved on IdentityProfile.raw. HubSpot does not
return an email_verified claim, a display name, or a user handle,
so those fields are always None.
IdentityProfile.tenancies answers "what scope of resources does this
token operate within?" — the workspace, organization, tenant,
instance, portal, or site the OAuth access token is bound to. It is a
tuple of TenancyContext entries because Atlassian OAuth 2.0 (3LO)
tokens can grant access to several Cloud sites at once and a singleton
shape would force a lossy "pick one" decision in the handler.
| Provider count | Provider examples |
|---|---|
() |
GitHub OAuth Apps, Typeform, consumer Google, personal Microsoft, Microsoft B2B guests |
| 1 entry | Slack, Linear, Notion, single-domain Microsoft Entra, Salesforce, HubSpot, Google Workspace |
| Many entries | Atlassian (Jira, Jira Service Management, Confluence); Microsoft Entra tenants with several verified domains |
Each TenancyContext exposes four normalized fields — id, name,
domain, owns_email_domain — plus a provider-specific raw payload
for fields that do not normalize cleanly. Each normalized field may
independently be None (or False for owns_email_domain) when
the provider's response does not assert that fact (for example,
Microsoft Entra workforce sign-in populates id, name, and domain
with owns_email_domain=True for each admin-verified domain of the
validated tenant; Google Workspace populates domain from the hd
claim and sets owns_email_domain=True; HubSpot populates only id
and domain with owns_email_domain=False). Persist id as the canonical key —
provider-mutable handles like Linear's urlKey should not be treated
as permanent identifiers.
identity = await client.fetch_identity(tokens)
for tenancy in identity.tenancies:
print(tenancy.id, tenancy.name, tenancy.domain)Two facts on IdentityProfile are load-bearing for identifying users
safely: provider (which IdP issued the token) and subject (the
provider's stable, opaque user ID). The recommended primary key for a
consumer's user or identity table is the tuple (provider, subject),
exposed via the identity_key() helper:
identity = await client.fetch_identity(tokens)
key = identity.identity_key() # ("google", "g-1") or None
if key is None:
raise AuthError("Provider did not return a stable subject")
user = get_or_create_by_identity_key(key)Email is a display label, not an identity. Use verified_email()
to surface the email at the call site only when the provider verified
it; otherwise treat the address as untrusted user input:
display = identity.verified_email() # None if not verified by providerThe verified-email assertion proves the user once controlled the inbox at the time of verification. It does not prove ongoing control, current employment, or that the email's domain belongs to any organization the user is affiliated with. For those questions, see Domain-bound tenancy access.
# DON'T
user = get_by_email(identity.email) # cross-provider hijack vectorTreating email as a stable cross-provider identifier lets any
identity that presents a verified copy of an existing user's email —
on any supported provider — silently link into that user's account.
The verified flag from a provider like GitHub is sticky once acquired;
there is no out-of-band revocation when the user loses control of the
mailbox. Use (provider, subject) instead.
A consumer keeping a separate identity table makes the recipe mechanical and supports explicit, opt-in cross-provider account linking:
oauth_identity
provider TEXT -- PK part 1: "google", "github", ...
subject TEXT -- PK part 2: provider's stable opaque user ID
user_id FK -> user.id
email_at_link TEXT -- audit snapshot, not a lookup field
email_verified_at_link BOOLEAN
linked_at TIMESTAMP
The user row keeps email as a display field only. Cross-provider
linking ("the same person, multiple providers") becomes an explicit
ceremony: an already-authenticated user adds a second identity by
completing OAuth on the second provider while logged in via the
first. Email lookups never silently merge accounts.
When a consumer wants to grant access to an organization on the basis of the user's email domain — for example, "anyone from acme.com joins the Acme tenant automatically" — the verified-email signal alone is not sufficient. A verified email proves inbox control; it does not prove that the IdP issuing the token controls the email's domain.
apron-auth surfaces the stronger fact via
IdentityProfile.owns_domain(). This returns True only when the
provider asserts that some tenancy controls that domain (Google
Workspace via the hd claim, or Microsoft Entra workforce sign-in via
the validated tenant's admin-verified domains; capability flag below).
Gate on the False case to refuse domain-based grants:
def join_org(identity: IdentityProfile, claimed_domain: str) -> Membership:
domain = claimed_domain.strip().lower()
if not identity.owns_domain(domain):
raise AuthError(f"No domain-owning assertion for {domain}")
return grant_membership(identity.identity_key(), domain)Matching is exact once whitespace is trimmed and case is folded. A
parent domain does not confer ownership of its subdomains — a tenant
verified for acme.com does not satisfy a gate on corp.acme.com.
owns_domain() folds its argument for the comparison only; it does not
hand back a canonical form. Whatever key you persist is yours to
normalize. Canonicalize once and use that value for both the gate and
the write, as above — otherwise " Example.COM " passes the gate and
is then stored alongside example.com as a second membership row.
Test the domain; do not pick one. A single tenant can assert
several domains at once: every Entra tenant has an
*.onmicrosoft.com domain alongside any custom domain, and Microsoft
Graph does not guarantee the order it lists them in. Reducing that set
to one entry and comparing against it yields an arbitrary answer, and
persisting the reduction latches the arbitrary choice permanently:
# DON'T — arbitrary which domain you get on a multi-domain tenant
owner = identity.domain_owning_tenancies()[0]
if owner.domain != claimed_domain:
raise AuthError(...)To enumerate or display the full set rather than test one domain, use
domain_owning_tenancies(), which returns every asserting tenancy:
verified = [t.domain for t in identity.domain_owning_tenancies()]
# ["contoso.com", "contoso.co.uk", "contoso.onmicrosoft.com"]ProviderConfig.can_assert_domain_ownership declares whether a
preset's tokens can in principle carry a domain-owning tenancy.
Consumers building a domain-gated tenancy flow can reject incapable
providers at startup, rather than discovering the gap at login time:
config, _ = some_preset(client_id=..., client_secret=..., scopes=...)
if domain_gated_signin and not config.can_assert_domain_ownership:
raise ConfigError(
"This provider cannot assert domain ownership; do not "
"wire it up for domain-gated tenancy."
)Per-provider capability:
| Provider | can_assert_domain_ownership |
Mechanism |
|---|---|---|
True |
hd claim (Workspace accounts) |
|
| Microsoft | True |
Validated ID token + tenant's admin-verified domains (workforce) |
| GitHub | False |
No structural mechanism |
| Slack | False |
Workspace is not a domain authority |
| Linear | False |
Workspace is not a domain authority |
| Notion | False |
Workspace is not a domain authority |
| HubSpot | False |
Portal is not a domain authority |
| Atlassian | False |
Site is not a domain authority |
| Salesforce | False |
Custom-domain investigation deferred |
| Typeform | False |
No tenancy concept |
False is the security-preserving default. Future provider opt-ins
are strictly additive — a flag flipping from False to True only
loosens a gate, never tightens one. Pin a known-good provider list in
your config if you want changes to require an explicit code review.
A common pattern is granting a role (admin, member, …) based on a specific email address. The safe variant always pairs the email check with a domain-ownership check, so a verified email from an incapable provider cannot satisfy the allowlist alone:
ADMIN_EMAILS = {"founder@example.com"}
def is_admin(identity: IdentityProfile) -> bool:
return (
identity.owns_domain("example.com")
and identity.verified_email() in ADMIN_EMAILS
)Without the owns_domain() check, any provider returning
email_verified=True for founder@example.com would grant admin —
including a personal GitHub account that happens to have
founder@example.com verified on it.
When a user is offboarded by the IdP that controls their email's domain (the Workspace admin disables the account, for example), the provider's tokens stop refreshing. Consumers wanting their app sessions to reflect that change in near-real-time must refresh on a cadence shorter than the staleness window they are willing to accept.
apron-auth does not enforce refresh cadence. The recommended shape is:
- Issue your own short-lived application session (e.g. a JWT with a TTL of minutes, not hours).
- On session refresh, call
client.refresh_token(...)against the provider; if refresh fails permanently (PermanentOAuthError), revoke the application session. - For long-running background tasks that hold a refresh token, run the same check periodically.
There is no analogous deprovisioning path for providers that lack
domain-ownership (everything in the capability table above with
False). For those providers, deprovisioning at the OAuth layer
relies on the user revoking their authorization with the provider,
or the consumer maintaining an out-of-band revocation list.
Refreshing can fail permanently (the user revoked access, the client was deregistered) or transiently (network blip, rate limit). apron-auth tells you which.
from apron_auth import PermanentOAuthError
try:
tokens = await client.refresh_token(tokens.refresh_token)
except PermanentOAuthError:
# The token can't be recovered — delete it and re-authenticate the user.
passBy default, invalid_grant, unauthorized_client, and invalid_client are treated as permanent. If your provider uses non-standard error codes for the same thing, you can extend the set:
client = OAuthClient(
config,
permanent_error_codes={"token_revoked", "account_suspended"},
)These merge with the defaults — you can inspect them via OAuthClient.DEFAULT_PERMANENT_ERROR_CODES.
client = OAuthClient(config, revocation_handler=revocation_handler)
await client.revoke_token(tokens.access_token)If you need to persist OAuth state across requests (e.g. between the redirect and the callback), implement the StateStore protocol.
from apron_auth import StateStore, OAuthPendingState
class MyStateStore:
async def save(self, state: OAuthPendingState) -> None:
# Persist state, keyed by state.state.
...
async def consume(self, state_key: str) -> OAuthPendingState | None:
# Look up and invalidate in one step. Return None if it's missing or expired.
...
client = OAuthClient(config, state_store=MyStateStore())
url, pending_state = await client.get_authorization_url(
redirect_uri="https://yourapp.com/callback",
)
# When the callback arrives, pass the state parameter and the code.
# The store is consumed automatically.
tokens = await client.exchange_code(code="...", state="state-from-callback")If your application needs to carry context through the OAuth flow (e.g. which user or tenant initiated it), pass metadata when building the authorization URL. apron-auth carries it opaquely through the StateStore and surfaces it on TokenSet.context after auto-consume.
url, pending_state = await client.get_authorization_url(
redirect_uri="https://yourapp.com/callback",
metadata={"user_id": "U123", "tenant_id": "T456"},
)
# On callback, context comes back on the TokenSet.
tokens = await client.exchange_code(code="...", state="state-from-callback")
print(tokens.context["user_id"]) # "U123"
print(tokens.context["tenant_id"]) # "T456"
# Provider response extras (e.g. Slack's team_id) are separate.
print(tokens.metadata) # {"team_id": "T123", ...}| Provider | Preset | Revocation | disconnect_fully_revokes |
|---|---|---|---|
google.preset(...) |
POST with query param | True |
|
| GitHub | github.preset(...) |
DELETE with Basic auth | True |
| Slack | slack.preset(...) |
GET with query param | False |
| Notion | notion.preset(...) |
POST with Basic auth | False |
| Microsoft | microsoft.preset(...) |
— | False |
| Atlassian | atlassian.preset(...) |
RFC 7009 POST | False |
| Linear | linear.preset(...) |
RFC 7009 POST | False |
| Salesforce | salesforce.preset(...) |
RFC 7009 POST | False |
| Typeform | typeform.preset(...) |
— | False |
| HubSpot | hubspot.preset(...) |
DELETE refresh-token | False |
Some providers' revocation endpoints fully remove the user's portal-level OAuth grant; others only invalidate the current token while the grant lingers. apron-auth surfaces this difference as ProviderConfig.disconnect_fully_revokes so consumers can offer the right scope-reduction UX without rebuilding the per-provider truth table inline.
| Tier | Meaning | When |
|---|---|---|
| 1 | Automatic scope reduction: revoke + re-auth presents a fresh consent screen, narrower scopes take effect. | disconnect_fully_revokes is True |
| 3 | Manual via provider settings: deep-link the user to the provider's app management page; revoke alone is not enough. | disconnect_fully_revokes is False |
from apron_auth.providers import google, hubspot
google_config, _ = google.preset(...)
hubspot_config, _ = hubspot.preset(...)
if google_config.disconnect_fully_revokes:
... # tier 1: trigger revoke + re-auth in-app
else:
... # tier 3: open the provider's app-management pageThe default for unconfigured ProviderConfig is False — under-claiming the capability harmlessly falls back to the manual deep-link path.
Trello's API uses OAuth 1.0 exclusively — there is no OAuth 2.0 support yet. Atlassian has announced plans to introduce OAuth 2.0 (3LO) for Trello, but no launch date has been committed.
Because apron-auth is an OAuth 2.0 library, Trello is not supported. If your application needs Trello, handle its OAuth 1.0 flow separately (e.g. with authlib). apron-tools provides Trello tool definitions — you just need to bring your own token.
When Trello ships OAuth 2.0, a preset will be added here.
All exceptions inherit from OAuthError.
| Exception | When it's raised |
|---|---|
TokenExchangeError |
Code exchange failed at the token endpoint. |
TokenRefreshError |
Refresh failed, but it might work if you try again (transient). |
PermanentOAuthError |
The token is gone — invalid_grant, unauthorized_client, or invalid_client. Delete it and re-authenticate. |
RevocationError |
The provider rejected the revocation request. |
StateError |
OAuth state was invalid, expired, or already used. |
ConfigurationError |
Something's wrong with the provider config (e.g. missing redirect_uri). |
Requires uv.
make setup # Install uv, create venv, sync deps, install pre-commit hooks
make test # Run unit tests
make lint # Run pre-commit hooks (ruff, ty, detect-secrets)Or using uv directly:
uv sync --group dev
uv run pytest tests
uv run pre-commit run --all-files