🐍 gatekeeper-sdk (Python)#

Typed Python client for the Gatekeeper API, built on httpx.

🚀 Usage#

Construct a GatekeeperCore once, then build only the services you need over it - each is a standalone class.

from gatekeeper import GatekeeperCore, AuthService, KeysService, BillingService, is_mfa_challenge
 
core = GatekeeperCore("https://gatekeeper-api.example.workers.dev")
 
# Auth
auth = AuthService(core)
tokens = auth.signup("a@b.com", "hunter2pass")
core.set_token(tokens["accessToken"])
me = auth.me()
 
# MFA - if login returns a challenge instead of tokens, complete it
login = auth.login("a@b.com", "hunter2pass")
if is_mfa_challenge(login):
    # MfaService(core).verify_challenge(login["challengeToken"], "123456")
    ...
 
# API keys
keys = KeysService(core)
created = keys.create(tenant_id="t1", scopes=["read"])
 
# Billing
billing = BillingService(core)
plans = billing.plans()

Use the core as a context manager to close the underlying httpx client:

with GatekeeperCore(url, token=token) as core:
    AuthService(core).me()

🧩 Design#

Property	Detail
Composition	`XService(core)` - each service depends only on `core.request()` / `core.request_text()`
Core	holds base URL, bearer token (mutable via `core.set_token()`), and the httpx client
Custom transport	pass `http=httpx.Client(...)` to `GatekeeperCore` (proxies, mounts, mocks)
Transport	httpx (sync)
Errors	non-ok responses raise `GatekeeperError` with `.status`; `.retry_after` holds the `Retry-After` seconds on `429`
Envelope	unwraps the API's `{ ok, data, error }`; methods return `data`
Types	`TypedDict` hints in `gatekeeper.types`

⚙️ Configuration#

Global config on the core, per-service defaults on the service (overridable per call):

core = GatekeeperCore(
    base_url,
    token=token,
    timeout=10.0,
    default_headers={"x-trace": "abc"},
    user_agent="myapp/1.0",
)
 
# or from env: GATEKEEPER_BASE_URL + GATEKEEPER_TOKEN
core2 = GatekeeperCore.from_env()
 
# per-service defaults
keys = KeysService(core, default_scopes=["read"], default_quota_period="month")
audit = AuditService(core, default_format="csv")
tenants = TenantsService(core, default_role="admin")

Constants ship with their service: QUOTA_PERIODS, AUDIT_EXPORT_FORMATS, TENANT_ROLES.

🔌 Services#

Service	What it does
`AuthService`	signup, login, refresh, password reset, MFA login
`TenantsService`	create tenants, manage members
`MfaService`	TOTP enroll / verify / disable
`KeysService`	API keys: create, validate, JWT exchange
`UsageService`	quota checks + metered usage
`PermissionsService`	tenant RBAC roles + checks
`WebhooksService`	endpoints, dispatch, deliveries
`AuditService`	record / query / export audit log
`BillingService`	plans, subscriptions, entitlements, invoice
`OAuthService`	provider authorize + callback
`RateLimitService`	standalone rate-limit check
`PlatformBillingService`	platform-scoped subscription override
`PlatformJobsService`	inspect + retry background jobs
`PlatformServiceAccountsService`	platform service accounts: create, list, revoke

Each maps one-to-one to an API route group. Construct any subset over a shared GatekeeperCore. Per-service usage + methods: click a service above.