Skip to content

Quickstarts

These quickstarts are written for tenant owners, application developers, and operators who need a working SigID integration. Each flow ends with a clear definition of done so you can hand the result to another team without hidden context.

Before you start

Gather the following before creating production resources:

Item Why it matters
Tenant display name Shown in login, consent, email, and administrator screens
Production application URLs Required for redirect URI and allowed-origin checks
Administrator list Determines who can change tenant security settings
Required scopes Controls what user, organization, agent, or wallet data apps can request
Identity providers Determines whether you need social OAuth, enterprise OIDC SSO, SIWE, or passkeys
Event receiver URL Needed if your application consumes webhooks or audit events

Recommended order

Start with one tenant, one web application, one administrator, and one test user. Add organizations, SSO, agents, and webhooks after basic login works.

Create a tenant

  1. Sign in to the SigID dashboard.
  2. Create a tenant for the product, workspace, customer account, or organization boundary you manage.
  3. Choose a stable tenant slug. Treat it as a durable operational identifier.
  4. Set the customer-facing tenant name and support contact.
  5. Add at least two administrators before inviting broader teams.
  6. Review the default authentication, session, and consent settings.

Definition of done:

  • The tenant has a recognizable display name.
  • At least two administrators can access the dashboard.
  • The tenant slug, production domain, and owner team are recorded internally.
  • Audit logging is enabled for administrator actions.

Add login to a web application

Use Authorization Code with PKCE for browser, mobile, and desktop applications. Do not use implicit flow.

Register a development application from a terminal or coding agent:

npm exec @sigid/init -- \
  --issuer https://auth.example.com \
  --tenant acme \
  --registration-token "$SIGID_DCR_INITIAL_ACCESS_TOKEN"

The command uses Dynamic Client Registration, creates a public PKCE client by default, and writes SIGID_ISSUER_URL, SIGID_CLIENT_ID, SIGID_REDIRECT_URI, and SIGID_SCOPES to .env.local.

Manual setup follows the same model:

  1. Open the tenant dashboard.
  2. Create an application.
  3. Add development and production redirect URIs.
  4. Add allowed browser origins for frontend calls.
  5. Choose the scopes the application needs for its first release.
  6. Configure your frontend to redirect users to /oauth/authorize.
  7. Exchange the returned authorization code at /oauth/token.
  8. Validate access tokens in your backend before serving protected resources.
  9. Use the ID token or /userinfo only for claims the user consented to share.

Minimum authorization request:

GET /oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20email
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256
  &state=OPAQUE_CSRF_VALUE

Definition of done:

  • A test user can sign in and return to the application.
  • The backend rejects tokens with the wrong issuer, audience, signature, expiration, tenant, or scope.
  • The application stores the tenant-local subject as its user key.
  • Logout and session refresh behavior are documented for support.

Configure hosted login

Hosted login is the user-facing trust boundary. Make it recognizable and keep the security posture consistent with your product.

Setting Recommended practice
Application name Match the product name users expect
Redirect URIs Use exact HTTPS URLs in production
Allowed origins Include only browser origins you control
Branding Use tenant-approved names, colors, and support links
Scopes Start narrow and add only when a workflow needs more access
Consent text Explain what the application receives in user terms
Step-up rules Require MFA for sensitive or administrative actions

Definition of done:

  • Login and consent screens are recognizable to real users.
  • Development callback URLs are separated from production callback URLs.
  • Sensitive actions require fresh authentication, consent, or MFA.

Invite users

Tenant users are membership records. They do not replace the person's global SigID account.

  1. Open the tenant user area.
  2. Invite users by email or pre-provision them before first sign-in.
  3. Assign the least-privileged role needed for their job.
  4. Place users in organizations when access is business-account scoped.
  5. Use suspension for temporary access removal.
  6. Use removal when the user should no longer belong to the tenant.

Definition of done:

  • The invited user can accept the invitation and sign in.
  • The user's role is visible in the tenant user list.
  • Suspension blocks future access without deleting audit history.

Add an organization

Organizations model teams, companies, departments, or customer accounts within the tenant.

  1. Create the organization.
  2. Assign an owner or administrator.
  3. Invite members manually or connect enterprise SSO.
  4. Verify domains before enabling routing or auto-join.
  5. Map organization roles to application permissions.
  6. Review organization audit events after the first login.

Definition of done:

  • The organization has at least one owner.
  • Members can sign in and receive the expected organization context.
  • Domain verification and SSO enforcement are tested with a non-admin user.

Register an AI agent

Agents are first-class principals. They can authenticate as themselves or act for users through delegated tokens.

  1. Create an agent record in the tenant dashboard.
  2. Attach an identity anchor such as ERC-8004, did:web, did:key, or client credentials.
  3. Complete challenge-response verification.
  4. Register signing keys or anchors needed for the agent's runtime.
  5. Grant only the scopes and delegations required by the agent.
  6. Use audit logs and webhooks to monitor agent activity.

Definition of done:

  • The agent has a verified identity anchor.
  • The agent can obtain a tenant-scoped token.
  • Delegated user access is narrower than the user's own access.
  • Sensitive tools require policy checks or human approval.

Register a webhook receiver

Use webhooks when your product needs asynchronous event updates.

  1. Create an HTTPS endpoint dedicated to SigID events.
  2. Register a webhook subscription in the tenant dashboard.
  3. Select the event types your application needs.
  4. Store the signing secret in your secret manager.
  5. Verify every delivery by recomputing the HMAC signature. See signature verification for the canonical string format and full verification steps.
  6. Deduplicate deliveries by X-SigID-Delivery.

For the full list of delivery headers, see Webhooks And Events.

  1. Return a 2xx response only after the event is safely accepted.

Definition of done:

  • Test delivery reaches your endpoint.
  • Invalid signatures are rejected.
  • Duplicate delivery IDs do not create duplicate side effects.
  • Receiver failures are visible in your logs and alerting.

Go live

See the production checklist before exposing SigID login to production users.

Related by summary, tags, categories, and content
Tenant Setup Set up a SigID tenant with durable boundaries, environments, OAuth clients, branding, administrators, and production-ready defaults. tenant setup environments oauth clients Applications And OAuth Integrate applications with SigID using OAuth 2.1, OpenID Connect, PKCE, token validation, consent, and tenant-scoped subjects. oauth oidc pkce API And SDKs Choose API and SDK integration paths for login, protected APIs, tenant administration, webhooks, and agent workflows. api sdks oauth