Workspace Admin Quickstart¶
Use this guide when you are responsible for preparing SigID before developers or users start testing.
Time: 20-30 minutes for a development workspace.
What You Will Prepare¶
- one workspace or tenant
- one application users recognize
- callback, logout, web-origin, and CORS values
- sign-in methods for testing
- one test user
- a developer handoff packet
1. Create Or Choose A Workspace¶
Ask the admin which environment this setup targets, then use a separate workspace or tenant for it: Development (local callback URLs, test users, non-production client IDs), Staging (pre-production domains, test SSO, launch rehearsal), or Production (real domains, real users, production support process).
Before moving on, confirm all four items: primary owner assigned, backup owner assigned, support contact known, and an environment name that is obvious.
Owners and the support contact are human assignments - if any is undecided, stop and have the admin name them. Access must not depend on one person.
Use a separate workspace or tenant for each environment:
| Environment | Recommended use |
|---|---|
| Development | Local callback URLs, test users, non-production client IDs |
| Staging | Pre-production domains, test SSO, launch rehearsal |
| Production | Real domains, real users, production support process |
Confirm:
- primary owner is assigned
- backup owner is assigned
- support contact is known
- environment name is obvious
2. Create The Application¶
In Dashboard, choose the tenant workspace, open Applications, then click Create Application (tenant-scoped route like /tenant/acme-labs/applications/register).
Work the form in order: Basics (user-recognizable name and short description), OAuth flows (start with Authorization Code with PKCE), Application URIs (exact callback, logout, web-origin, and CORS URLs for this environment), Token endpoint authentication (public client for browser apps; confidential only with a trusted backend), Scopes (start with openid profile email), Login posture (default for development), then Review the URLs once more before creating.
After creation, open the application detail and copy the Client ID for the developer handoff packet. Never place a client secret in a browser app.
If sign-in later fails on redirect, check for a trailing-slash or scheme mismatch against the exact app callback URL.
In Dashboard, choose the tenant workspace, open Applications, then click
Create Application. The route is tenant-scoped, for example
/tenant/acme-labs/applications/register.
Follow the create form in this order:
| Form step | What to enter |
|---|---|
| Basics | Choose the app shape, then set a user-recognizable name and short description. |
| OAuth flows | Start with Authorization Code with PKCE for browser, mobile, and desktop apps. |
| Application URIs | Add exact callback, logout, web-origin, and CORS URLs for this environment. |
| Token endpoint authentication | Use a public client for browser apps; use a confidential client only when a trusted backend stores the secret. |
| Scopes | Start narrow: openid profile email, then add API scopes only when developers need them. |
| Login posture | Start with the default posture for development, then tighten sensitive apps before production. |
| Review | Check URLs one more time before creating the app. |
Use these recommendations while filling the form:
| Field | Recommendation |
|---|---|
| Name | Use the product or dashboard name users already know |
| Client type | Public PKCE for browser/mobile/desktop apps; confidential only when a trusted backend stores the secret |
| OAuth flows | Start with Authorization Code with PKCE |
| Allowed Callback URLs | Exact callback URLs for this environment |
| Allowed Logout URLs | Where users may land after sign-out |
| Allowed Web Origins | Browser origins allowed to start or complete login |
| Allowed Origins (CORS) | Browser origins allowed for SDK/API browser calls |
| Scopes | Start narrow: openid profile email, then add API scopes only when needed |
| API audience | The backend resource identifier developers will validate |
Local Next.js example:
Allowed Callback URL: http://localhost:3000/auth/callback
Allowed Logout URL: http://localhost:3000
Allowed Web Origin: http://localhost:3000
Allowed Origins: http://localhost:3000
After creation, open the application detail and copy the Client ID for the developer handoff packet. Keep any client secret out of browser apps.
3. Choose Login Methods¶
For a first development test: enable Passkey if the test environment supports it, keep email and password as a fallback, enable magic link or email OTP only if email delivery is configured, and enable MFA or fresh verification for administrator or sensitive-action testing.
Add SSO only after the basic app login works.
Before enabling each method, confirm with the admin that support knows what users should do when that method fails - do not launch a method without that answer.
For a first development test:
| Method | Recommendation |
|---|---|
| Passkey | Enable if the test environment supports it |
| Email and password | Keep as a fallback for early testing |
| Magic link or email OTP | Enable only if email delivery is configured |
| MFA or fresh verification | Enable for administrator or sensitive-action testing |
| SSO | Add after the basic app login works |
Do not launch a method until support knows what users should do when it fails.
4. Invite Test Users¶
Invite at least three testers: one normal user, one workspace administrator, and one support or QA user.
Ask each tester to start from the real app, sign in with SigID, and confirm they return to the app - do not only test from the SigID surface.
If a tester does not return to the app, recheck the Allowed Callback URLs for an exact-match problem before changing anything else.
Invite at least:
- one normal user
- one workspace administrator
- one support or QA user
Ask each tester to start from the real app, sign in with SigID, and confirm they return to the app. Do not only test from the SigID surface.
5. Hand Off To Developers¶
Compile the packet from this environment only: issuer URL, Client ID (copied from the application), redirect URI (exact callback URL), logout URL, allowed origin, scopes (e.g. openid profile email projects:read), API audience, tenant ID or slug, client type (public PKCE or confidential), and a non-admin test account.
Verify every value came from the same workspace - mixing environments makes a production app trust the wrong issuer.
Then send developers to the Next.js Quickstart or React SPA Quickstart.
Give developers this packet:
| Value | Example |
|---|---|
| Issuer URL | https://identity.example.com |
| Client ID | copied from the application |
| Redirect URI | exact callback URL |
| Logout URL | exact logout URL |
| Allowed origin | browser origin |
| Scopes | openid profile email projects:read |
| API audience | https://api.example.com/projects |
| Tenant ID or slug | tenant that owns the application |
| Client type | public PKCE or confidential |
| Test account | non-admin test user |
Then send them to Next.js Quickstart or React SPA Quickstart.
Done When¶
- application name and logo are recognizable
- callback, logout, web-origin, and CORS values match the app exactly
- at least one test user can sign in from the real app and return
- support knows the recovery path for failed sign-in
- developers have issuer, client ID, redirect URI, scopes, audience, and tenant
- production secrets are not used in development
Common Mistakes¶
| Mistake | Fix |
|---|---|
| Callback URL has a trailing slash mismatch | Copy the exact URL from the app route. |
| Production app uses development issuer | Keep issuer, client ID, redirect URI, audience, and tenant from one environment. |
| Browser app receives a client secret | Use a public PKCE client for browser apps. |
| SSO is added before basic login works | Prove basic app login first, then add organization SSO. |
| User starts from SigID instead of the app | Test from the app users will actually open. |