Add tenants.create_user and get_user_tenants

[zeevmoney]

Linear issues

• PER-16678: Add tenants.create_user (with add_user as a deprecated alias) and get_user_tenants to the Python SDK.
• PER-16710: The PDP leaves members with no role out of /user-tenants; the SDK documents and tests the current behaviour.
• PER-16337: Python SDK parity with the other SDKs; this PR covers P1 items 2 and 5.

Why

The SDK could list a tenant's users and remove them, but it could not add a user to a tenant through the tenant users route. It also had no way to ask the PDP which tenants a user belongs to. The Java SDK has the second as getUserTenants.

What changed

• permit.api.tenants.create_user(tenant_key, user_data) -> UserRead, on the async and blocking clients. It posts the user (UserCreate or an equivalent dict) to /v2/facts/{proj}/{env}/tenants/{tenant}/users. It always calls the Permit REST API, even with proxy_facts_via_pdp, because the PDP forwards this route without waiting for the policy sync. The API creates a new user who belongs to the tenant with no role. Any role_assignments in the user data are granted in the tenant each one names. An existing key gets 409 (PermitAlreadyExistsError). A missing tenant, or a missing role, tenant or resource named by an inline grant, gets 404 (PermitNotFoundError). It needs an environment-level API key, or a broader key with the SDK's API context set to the environment. TenantsApi builds this client through a new API-only property. The routing of its other methods is unchanged.
• permit.get_user_tenants(user, context=None) -> list[TenantDetails], on permit.Permit, permit.sync.Permit and the enforcer. It posts {"user", "context"} to the PDP's /user-tenants route. The user is serialized as check() serializes it, and the context is merged over the context store. The PDP lists the tenants in which the user holds a tenant-level role. A member with no role is not listed. Only the container PDP serves the route. When the PDP answers 404, as the cloud PDP does, the SDK raises a PermitConnectionError saying the call needs a container PDP. Any other error status raises a PermitConnectionError with the status and the redacted error body, as check() does. A PDP that cannot be reached raises the same connection error as the other PDP calls.
• permit.api.tenants.add_user() is a deprecated alias of create_user(): it issues one DeprecationWarning at the caller's line, then calls create_user(). It will be removed in permit 4.0. The README lists it under Deprecations.
• TenantDetails(key, attributes) in permit.enforcement.interfaces, exported from permit next to AuthorizedUsersResult.
• The delete_tenant_user docstring now says what the API does. It removes the user's tenant-level roles in the tenant. It answers 404, raised as a PermitApiError, when the user holds none there, which includes a member that create_user() created; such a member is removed with users.delete(). The user stays a member while they hold a role in another tenant. The API deletes the user once no tenant-level role is left in any tenant.
• A "Tenant membership" section in the README, after Groups. The sync stub (permit/_sync_types.pyi) is regenerated, and tests/type_check/consumer.py calls both methods on both clients.
• Tests:
  • tests/test_tenant_membership_offline.py: 71 offline wire tests.
  • tests/test_tenant_membership_e2e.py: 3 e2e tests. The two that call get_user_tenants skip, with a reason, when the PDP is the cloud PDP.
  • tests/test_cloud_pdp_e2e.py: a new test checks that the cloud PDP's 404 for get_user_tenants raises the container-PDP error.
  • tests/test_fix_logging.py: the API key redaction test now also covers get_user_tenants.
  • tests/utils.py: now holds CLOUD_PDP_URL and delete_quietly_blocking, shared with the groups e2e tests.
• CONTRIBUTING and the e2e (cloud PDP) workflow comment describe the new tests.

Behaviour changes

None for existing methods. create_user, its deprecated alias add_user, get_user_tenants and the TenantDetails export are new. delete_tenant_user changes only in its docstring.

How it was tested

• Offline suite: 545 passed, 3 skipped on pydantic 2 and on pydantic 1, with 0 warnings (warnings are errors). The base had 472 passed and 3 skipped.
• Strict mypy on both pydantic lanes: no issues in 96 source files. tests/test_typing_surface.py (stub drift, consumer type check): 3 passed on both lanes.
• pre-commit run --all-files (ruff, ruff format, mypy, typos, uv lock --check), actionlint and zizmor: no findings.
• The offline wire tests assert the exact method, path, query, headers and JSON body of each call. They cover create_user with proxy_facts_via_pdp on and off, and get_user_tenants with a string user and a dict user (with attributes), with and without context. They also cover a PDP 404, a PDP 500, an unreachable PDP and the parsed return types.
• Mutation check: the alias test fails when add_user stops warning or stops passing its arguments through. 21 mutants of the new code, all caught by the offline tests. They include create_user through the PDP proxy, wrong path or verb, a dropped body or context, a missing 404 branch, an unredacted or missing error body, an unparsed response, the sync override removed, the export removed and a stale stub. The cloud-PDP test passes only on a 404; it fails on 200, 401, 405, 500 and an unreachable PDP.
• The e2e module collects and type-checks. It passes (3 passed) against a local in-memory stand-in for the API and PDP that behaves as the API does for tenant users. Eleven broken variants of that stand-in each make it fail. CI runs it against the real API and a container PDP.

Owner actions before merge

• Check that the container-PDP pytest jobs and e2e (latest PDP image) pass. They are the first run of the e2e module against the real API and PDP.
• PER-16710 tracks whether get_user_tenants should list members with no role and whether delete_tenant_user should remove them. If the PDP or API changes, update the docstrings, README and e2e assertion with it.

🤖 Generated with Claude Code

[linear-code]

PER-16678

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.