Tenant Setup¶

Tenant setup turns SigID from a shared identity service into a configuration that matches your product, customers, support model, and security posture.

Plan the tenant boundary¶

A tenant should represent the boundary where applications, users, roles, policies, agents, billing, and audit logs are administered together.

Use one tenant when:

the same administrators manage all identity settings
applications share user membership and role policy
audit logs should be reviewed by the same operational team
billing and usage should roll up to one account

Use separate tenants when:

environments must be isolated, such as staging and production
customers require separate administration or contractual separation
applications have different security policies or support ownership
logs, users, agents, or billing must not mix

Tenant basics¶

Field	Guidance
Tenant name	Use the product, team, or customer-facing organization name
Tenant slug	Choose a stable identifier; avoid names that encode temporary projects
Support contact	Route login, consent, and recovery questions to the right team
Default policy	Start restrictive and expand by role, scope, or organization
Branding	Make hosted auth recognizable so users trust the login handoff
Administrators	Keep the admin list small, reviewed, and protected by MFA

Changing identifiers

Display names can change. Slugs, redirect URIs, client IDs, and tenant-local subjects should be treated as durable integration identifiers.

Environment model¶

Most teams use at least two tenants:

Environment	Purpose	Typical restrictions
Development	Local callback testing and SDK integration	Limited users, test domains, short-lived clients
Staging	Release validation with production-like settings	Realistic SSO, webhooks, roles, and policies
Production	User-facing identity	HTTPS only, reviewed administrators, monitored webhooks

Keep production data and development data separate. Do not reuse production client secrets, webhook secrets, redirect URIs, or SSO credentials in local development.

Application setup¶

Each application is an OAuth client. Create one application per deployable app, mobile client, CLI, backend service, or agent integration that needs distinct redirect URIs, credentials, scopes, or audit ownership.

Configure:

client type
allowed grant types
redirect URIs
allowed browser origins
requested scopes and token audience
logout and post-login behavior
token lifetime and refresh behavior
webhook subscriptions if the application receives events

Recommended defaults:

Application type	OAuth flow	Notes
Browser app	Authorization Code with PKCE	Exchange codes through a backend when possible
Native/mobile app	Authorization Code with PKCE	Use claimed HTTPS or platform redirect URIs
Backend service	Client Credentials	Store client secrets only server-side
CLI or device	Device Authorization	Poll according to the returned interval
Agent acting for user	Token Exchange	Require consent and policy limits

Authentication settings¶

Enable only the sign-in methods your users can understand and support. For all supported methods and descriptions, see Product Reference.

Key recommendations:

Method	Operational note
Email and password	Require MFA for privileged users
Passkeys	Prefer for administrators and high-risk users
Enterprise SSO	Verify domains before enforcement
Anonymous accounts	Define conversion and deletion behavior

Roles, scopes, and policies¶

Use all three layers deliberately:

Layer	Use for	Example
Roles	Human-readable access bundles	`admin`, `support`, `billing_manager`
Scopes	API and token permissions	`users:read`, `webhooks:manage`
Policies	Context-aware decisions	Require MFA before deleting an organization

Keep roles stable and understandable. Keep scopes narrow enough that APIs can check them directly. Use policies for conditions that depend on subject type, organization, risk, time, or delegation.

User and organization setup¶

Tenant administrators manage tenant membership. Users own their global SigID accounts, while tenants control whether those accounts can access tenant applications.

For individual access:

invite users by email
assign least-privileged roles
suspend users when access should pause
remove users when membership should end

For business-account access:

create organizations
verify domains
configure SSO
map identity-provider groups to roles
test deprovisioning before relying on directory sync

Hosted auth should make it obvious which application is requesting access.

Review:

application display name
tenant logo or visual identity
support and privacy links
consent descriptions for sensitive scopes
wording for delegated agent access
SSO routing messages

Consent should describe user-visible outcomes. Prefer "Allow Acme Analytics to read your organization membership" over an internal scope name alone.

Webhooks and audit readiness¶

Set up event delivery before production if your application needs automated sync, compliance evidence, or operational alerting.

Prepare:

one receiver endpoint per operational owner
event subscriptions limited to relevant event types
signature verification using the webhook secret
delivery ID deduplication
retry and dead-letter handling
alerts for exhausted or failing deliveries

Production checklist¶

Run this checklist before exposing SigID login to production users. For server-level production requirements (TLS, KMS, database SSL, production mode), see Server Configuration.

Production HTTPS redirect URIs are configured.
Development redirect URIs are removed or restricted.
Allowed origins match only trusted production frontends.
MFA is required for tenant and organization administrators.
Passkeys are enabled where your user base can support them.
SSO domains are verified and tested with a non-admin user.
Organization deprovisioning is tested.
Token validation checks issuer, audience, signature, expiration, tenant, and scopes.
Token lifetimes and refresh behavior match your risk model.
Webhook receivers verify signatures and deduplicate deliveries.
Audit logs are reviewed by the team that owns identity operations.
Billing, plan limits, and usage alerts are understood.
Recovery paths are documented for users and administrators.
Break-glass administrator access is documented and tested.
Login works for test users and administrators.
User suspension and session revocation are tested.
Client and webhook secrets are stored in a secret manager.
Support knows how to triage login, SSO, and consent issues.