Run The Example App¶

Ask about this page: Claude ChatGPT Grok

Use this guide when you want to see the SigID SDK path in a working local Next.js app before wiring your own application.

The example lives at examples/sdk-lab-next in a checkout of the SigID repository. Use the repository's Nix development environment (nix develop) for its pinned toolchain. Port 3008 is reserved for this lab; the Commerce demo uses 3006. The lab demonstrates the TypeScript / Next.js integration path.

What The Example Shows¶

Ask:

@sigid/client browser configuration
@sigid/react provider, sign-in, callback, session, protected UI, and logout
@sigid/next auth route handlers
requireAccessToken() on a protected API route
readable errors for callback, redirect, audience, and scope problems
local negative-path tests that do not require a live SigID tenant

New Evaluation: Provision A Sandbox¶

Ask:

A coding agent can create its own sandbox organization, tenant, application, and ordinary fixture user without a dashboard session. Use the agent quickstart and run:

npx @sigid/cli setup --name my-evaluation --framework nextjs \
  --redirect-uri http://localhost:3008/auth/callback

Map the returned tenant_issuer, client_id, and tenant_id using Integration Settings. The generic env_block is not a complete framework environment file; configure the API audience and scopes separately before testing the protected API. Setup derives allowed browser origins from the exact redirect URI; use your actual preview URL if it differs from the local example. Keep bootstrap management tokens, client secrets and fixture passwords in the private credential file. Configure the app with the public issuer/client ID; let the SDK manage its OAuth session. For unattended execution, supply the keystore passphrase through the CLI's --passphrase-file or --passphrase-stdin option.

Use the returned fixture human for real hosted sign-in, callback, signed-in UI, and logout. The CLI saves its once-only credentials in the owner-only, gitignored .dev/sandbox-fixture.env; keep that file private. Successful metadata probes or expected error responses do not prove hosted login works. Invite or hand off to the human operator after the integration works; activation of the sandbox for production still requires a human owner at AAL2.

For an existing managed workspace, follow the admin configuration path below. init requires an existing tenant and dynamic client registration may require an initial access token; neither replaces sandbox setup. For bootstrap failures, use the agent quickstart troubleshooting with the failing phase, CLI/server versions and sanitized problem/request ID.

Configure A SigID Application¶

Ask:

For an existing managed workspace, register this application configuration:

Field	Value
App URL	`http://localhost:3008`
Allowed Callback URL	`http://localhost:3008/auth/callback`
Allowed Logout URL	`http://localhost:3008`
Allowed Web Origin	`http://localhost:3008`
Allowed Origins (CORS)	`http://localhost:3008`
Client type	Public PKCE client
Scopes	`openid profile email projects:read:sdk-lab`
API audience	`https://api.example.local/projects`

Provision The Local Live-Proof Seed¶

Ask:

For live hosted login against the local container stack, you can self-provision the application seed instead of asking a workspace admin. With the dev stack up (just dev), run from the repository root:

just sdk-lab-provision

This ensures the demo tenant and the sigid-sdk-lab-next public PKCE app exist in the local development Postgres (via the sigid_privileged bootstrap functions) with the exact client ID, audience, callback, and scopes above. It is a dev-only seed, not a production provisioning path. To check readiness without writing anything, run just sdk-lab-readiness, which also prints the non-secret .env.local values to copy into the next step.

Create Environment Values¶

Ask:

From examples/sdk-lab-next, create .env.local:

NEXT_PUBLIC_SIGID_ISSUER_URL=http://auth.sigid.localhost:3000
NEXT_PUBLIC_SIGID_CLIENT_ID=sigid-sdk-lab-next
NEXT_PUBLIC_APP_URL=http://localhost:3008
NEXT_PUBLIC_SIGID_SCOPES="openid profile email projects:read:sdk-lab"

SIGID_API_AUDIENCE=https://api.example.local/projects
SIGID_API_SCOPE=projects:read:sdk-lab
SIGID_TENANT_ID=tenant-id-required

Replace the issuer, client ID, audience, scope, and tenant with values from your target deployment.

Run¶

Ask:

From the repository root:

cd examples/sdk-lab-next
bun install --frozen-lockfile
bun run dev

Open:

http://localhost:3008

What Success Looks Like¶

Ask:

Before live login, the local app should show:

heading: SigID Next.js SDK Lab
state: Signed out
button: Start hosted login
configured issuer, client ID, redirect URI, and scopes
link to the protected page

After live login with a real tenant, you should be able to:

Start hosted login.
Complete the SigID prompt.
Return to /auth/callback.
See signed-in user/session metadata without raw tokens.
Open /protected.
Call the local protected API.
Sign out.

Run The Local Gate¶

Ask:

With the dev server running, run this from the repository root:

SDK_LAB_NEXT_BASE_URL=http://localhost:3008 \
  bunx playwright test tests/playwright/sdk-lab-next/quality-gate.spec.ts

The gate proves local UI wiring and fail-closed API behavior for missing or malformed authorization. It does not prove live hosted login or successful token exchange; those require a real tenant and registered redirect URI.

If It Fails¶

Ask:

Symptom	Check
App cannot start	Run from `examples/sdk-lab-next` and keep workspace dependencies on `workspace:*`.
Button redirects to the wrong issuer	`NEXT_PUBLIC_SIGID_ISSUER_URL` is from the wrong environment.
Callback fails	The registered callback URL must be exactly `http://localhost:3008/auth/callback`.
Protected API returns `missing_bearer_token`	You are signed out or the frontend did not send a bearer token.
Protected API returns `wrong_audience`	`SIGID_API_AUDIENCE` does not match the token audience.
Protected API returns `wrong_tenant`	`SIGID_TENANT_ID` does not match the token tenant.

After the example works, copy the same sequence into your app with Next.js Quickstart.