User Management¶

Tenant administrators manage membership and access within their tenant. Users own their global SigID account, while tenants control whether that account can access tenant applications.

Tenant users¶

A tenant user is a membership record. It lets your tenant assign roles, provision access, suspend access, store tenant-local metadata, and audit administrative decisions without claiming ownership of the global user account.

Action	Use when	User impact
Invite	A person should join by email	User accepts before access is active
Pre-provision	Access should exist before first sign-in	User is linked when they authenticate
Assign role	User needs specific permissions	Token and policy decisions can include role context
Suspend	Access should pause temporarily	Future tenant access is blocked; history remains
Reactivate	A suspended user should return	Access resumes according to current roles
Remove	Membership should end	Tenant membership ends; audit history remains

Membership lifecycle¶

pre-provisioned or invited
  -> activated
  -> suspended
  -> reactivated
  -> removed

Common lifecycle patterns:

Pattern	Recommended flow
New employee	Pre-provision, assign role, place in organization, send invite
Contractor	Invite with narrow role, set review date, suspend at end date
Customer admin	Create organization, assign owner/admin role, require MFA
Compromised account	Suspend tenant user, revoke sessions, review grants and audit logs
Departure	Remove membership, revoke sessions, preserve audit trail

Tenant-local profile data¶

Tenants see only the data needed for their relationship with the user:

tenant membership status
tenant-local roles and metadata
consented profile fields
pairwise user subject
organization memberships inside the tenant
tenant activity and audit events

Tenants do not see unrelated tenant memberships or unshared global profile fields.

Use tenant-local subjects

Store the SigID tenant-local subject as the durable user key in your application. Email addresses can change, be unverified, or be shared across workflows.

Roles, scopes, and policies¶

Use roles for administrator-facing access groups and scopes for API-level authorization.

Concept	Owner	Example
Role	Tenant or organization admin	`support_agent`, `billing_admin`
Scope	Application/API owner	`users:read`, `organizations:manage`
Policy	Security or platform owner	Require MFA before role assignment

Design roles so support teams can explain them. Design scopes so APIs can enforce them. Use policies for contextual requirements such as MFA, delegated access, risk, organization, subject type, or time.

Invitations¶

Invitations should include:

recipient email
intended role
organization membership, when applicable
expiration policy
sender identity
audit trail for who sent it
locale or email template, when the tenant serves multiple regions

Before sending invitations at scale:

Test the invitation email with a non-admin user.
Confirm the link lands on the expected tenant-branded page.
Confirm expired links fail safely.
Confirm accepting an invitation produces the expected tenant role.
Confirm audit logs show invitation, acceptance, and role assignment events.

Pre-provisioning¶

Pre-provision users when access is managed outside the first sign-in flow, such as HR onboarding, enterprise directory sync, or customer import.

Pre-provisioned membership should include:

email or external identifier
provisioning source
intended role
organization membership
tenant-local metadata needed by your application

Do not grant broad permissions just because a user is pre-provisioned. Access should still require authentication and policy evaluation.

Suspension and removal¶

Suspension blocks future access while preserving membership history. Use it for temporary issues such as an employment pause, account investigation, or support hold.

Removal ends membership. Use it when the person should no longer belong to the tenant. Removal should not erase audit evidence for past administrative actions.

Incident workflow:

Suspend the tenant user.
Revoke active sessions and refresh tokens when appropriate.
Review recent login, organization, delegation, agent, and webhook activity.
Rotate application or API credentials if the user had access to secrets.
Record the reason and resolution in your incident system.

Access reviews¶

Run periodic access reviews for high-risk tenants. For the full access review checklist, see Admin Operations.

User-management-specific review items:

support impersonation or break-glass permissions
stale invitations
suspended users that should be removed

Good review output includes the reviewer, date, user list, exceptions, and follow-up actions.

API surface¶

Tenant user management is available through tenant-scoped API routes. Exact authorization depends on the caller's role and scopes.

Route	Purpose
`GET /api/v1/tenant-users`	List tenant users
`POST /api/v1/tenant-users`	Create or pre-provision a tenant user
`GET /api/v1/tenant-users/{tenant_user_id}`	Read one tenant user
`PATCH /api/v1/tenant-users/{tenant_user_id}`	Update metadata or roles
`DELETE /api/v1/tenant-users/{tenant_user_id}`	Remove tenant membership
`POST /api/v1/tenant-users/{tenant_user_id}/invite`	Send an invitation
`POST /api/v1/tenant-users/{tenant_user_id}/resend-invite`	Resend an invitation
`POST /api/v1/tenant-users/{tenant_user_id}/suspend`	Suspend access
`POST /api/v1/tenant-users/{tenant_user_id}/reactivate`	Restore access

For write routes, use idempotency keys when your client may retry after a network failure.