Skip to main content

teamusers Python SDK

This package verifies teamusers Ed25519 (EdDSA) access tokens, caches the service JWKS document, and provides local permission and ABAC authorization helpers. The verifier and middleware are synchronous; no event loop is required for ordinary SDK use.

Install

python -m pip install teamusers-sdk

For a checkout, install the local package instead:

python -m pip install ./sdk/python

NATS permission invalidation is optional:

python -m pip install 'teamusers-sdk[nats-py]'

Verification

from teamusers_sdk import Verifier

verifier = Verifier("https://iam.example.com", audience="orders")
claims = verifier.verify(access_token)

print(claims.subject, claims.kind, claims.perm_ver)

The second positional argument is the expected audience and defaults to "teamusers". A custom synchronous fetcher(url) can be supplied for an application HTTP transport or tests. cache_ttl is measured in seconds. Concurrent verification calls share one JWKS fetch, including a key-ID miss refresh.

Verifier.verify returns an immutable Claims object after checking the Ed25519 signature, issuer, expiration, exactly-one-entry audience, and required application claims.

Field Type Meaning
subject (sub) str Non-empty user or service subject
team str Optional team claim, or "" when absent
kind Literal["user", "service"] Subject kind
perm_ver (permVer) int Non-negative permission version
expiry (exp) datetime Expiration in UTC; exp exposes Unix seconds
audience (aud) str or tuple[str, ...] Verified JWT audience; lists must contain exactly one value
auth_time (authTime) int Authentication time in Unix seconds; 0 when absent
amr tuple[str, ...] Authentication methods; empty when absent

Legacy tokens without auth_time or amr remain valid and expose the defaults above.

Verification failures use typed exceptions: JWKSFetchError for key retrieval, TokenVerificationError for signature/JOSE failures, and TokenClaimsError for invalid application claims. All inherit from SDKError.

Permissions

from teamusers_sdk import PermissionsClient

permissions = PermissionsClient(
    "https://iam.example.com",
    service_token="service-token",
)
entry = permissions.Get("user-id", claims.perm_ver)
allowed, reason = permissions.Allow(claims, "orders:read:team", {"team_id": "team-1"})

Permission entries are fetched from GET /authz/permissions/{userID}, cached for two minutes by default, and single-flighted per user. A token perm_ver mismatch bypasses the cached entry. Use Invalidate(user_id), InvalidateAll(), or Clear() after an application-side change. Check(subject, permission, resource) performs the authoritative POST /authz/check request.

Permission keys use resource:action:scope grammar. Actions and scopes may use their documented wildcards; a leading ! is an explicit deny and wins against a matching allow. Parse, Validate, String, Match, and MatchKeys are available in Go-shaped and Pythonic spellings.

Conditions and middleware

Conditions are compiled by CompileCondition without an expression-language dependency. The supported context is subject.id, subject.kind, resource.owner_id, resource.team_id, resource.attrs[...], and request.time, with boolean operators, comparisons, in, and scalar literals. Sources are limited to 4 KiB and unsupported or failed evaluations deny access.

from teamusers_sdk import Client, Require

client = Client(verifier, permissions)
check = Require(client, request, claims, "orders:read:team", {"team_id": "team-1"})

Authenticate(request, verifier) returns Claims or raises UnauthorizedError (HTTP 401). Require returns Claims or raises ForbiddenError (HTTP 403). Both accept the minimal request shape {"headers": ..., "method": ...}.

RequireFresh(max_age_seconds) returns a guard measured in seconds. It accepts the request and already verified claims, returning the claims when auth_time is fresh; missing, future, or stale timestamps raise ForbiddenError with step_up_required. Missing claims raise UnauthorizedError:

from teamusers_sdk import RequireFresh

fresh = RequireFresh(600)
claims = fresh(request, claims)

Event invalidation

subscription = permissions.SubscribePermissions(
    "nats://127.0.0.1:4222",
    lambda user_ids: print(user_ids),
)
# later
subscription.Close()

The optional subscription listens to iam.perm.changed, iam.user.disabled, and iam.role.updated, invalidating each event's user_ids. Tests and applications that already own a connection can inject a subscription source object with subscribe(subject, callback) instead of a URL. The missing optional dependency is reported as NATSUnavailableError when SubscribePermissions is called; importing the core SDK never requires NATS.

User deletion lifecycle events

SubscribeUserDeleted listens to iam.user.deleted. The validated event has event_id, type, user_id, and at; changed_fields is omitted:

from teamusers_sdk import SubscribeUserDeleted

subscription = SubscribeUserDeleted(
    "nats://127.0.0.1:4222",
    lambda event: print(event["user_id"], event["event_id"]),
)
if subscription is not None:
    subscription.close()

Metadata

Release files for teamusers-sdk 0.2.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 teamusers-sdk 0.2.0
File Size Uploaded Provenance Actions
teamusers_sdk-0.2.0.tar.gz 30.5 kB With provenance Details for teamusers_sdk-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for teamusers-sdk 0.2.0
File Interpreter ABI Platform Actions
teamusers_sdk-0.2.0-py3-none-any.whl Python 3 none any Details for teamusers_sdk-0.2.0-py3-none-any.whl

Total release size: 58.1 kB

Release files / teamusers_sdk-0.2.0.tar.gz

Download URL teamusers_sdk-0.2.0.tar.gz
Size 30.5 kB
Tags Source
SHA-256 checksum
How to use checksums
28d8fe9e485d513caf3fb58bde5fa62ec99cf6a83cb79a5ad991eaca70b5e72c
BLAKE2b-256 checksum
How to use checksums
66379b3a4ebbe546b697fd3b7e23dc2f740d172730575afc25c31c0c23659ae2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / teamusers_sdk-0.2.0-py3-none-any.whl

Download URL teamusers_sdk-0.2.0-py3-none-any.whl
Size 27.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c49aaca8fc3aa7c28a44ff1fd0ad6a2a265289bfc7dcf393dcb58d5759c233f9
BLAKE2b-256 checksum
How to use checksums
887ec618b2f251244258df99636f55765713b1d18a7d3b9dc42fc2f8f23f2819
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Security for teamusers-sdk 0.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for teamusers_sdk-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

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.

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