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.3.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 |
|---|---|---|---|---|
| teamusers_sdk-0.3.0.tar.gz | 31.0 kB | With provenance | Details for teamusers_sdk-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| teamusers_sdk-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for teamusers_sdk-0.3.0-py3-none-any.whl |
Total release size: 58.8 kB
Release files / teamusers_sdk-0.3.0.tar.gz
| Download URL | teamusers_sdk-0.3.0.tar.gz |
|---|---|
| Size | 31.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6a3dc1a89a6ae4454f779ccd0f4085e841870e6e69ae77f1ae306b58b1f12a15
|
|
BLAKE2b-256 checksum How to use checksums |
f365420fac2e63bc151acae6fd9651f1a46d78bd1106a27694bbc3c38700ed3b
|
| 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 5, 2026.
Transparency logRelease files / teamusers_sdk-0.3.0-py3-none-any.whl
| Download URL | teamusers_sdk-0.3.0-py3-none-any.whl |
|---|---|
| Size | 27.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
35d6b2bdaa755e54a35b2f8eb1fd85573a2ba25ac22c9849411e6c77297229ae
|
|
BLAKE2b-256 checksum How to use checksums |
6cdba7b052f9ec4f39b7455a402d75056671932006510df0c1ed292fe893608c
|
| 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 5, 2026.
Transparency logSecurity for teamusers-sdk 0.3.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.
Attestation for teamusers_sdk-0.3.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 5, 2026.
Transparency logA 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.