Run The Example App¶

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. It is an integration lab for the current TypeScript / Next.js golden path.

What The Example Shows¶

@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

Configure A SigID Application¶

For live hosted login, register this application configuration:

Field	Value
App URL	`http://localhost:3006`
Allowed Callback URL	`http://localhost:3006/auth/callback`
Allowed Logout URL	`http://localhost:3006`
Allowed Web Origin	`http://localhost:3006`
Allowed Origins (CORS)	`http://localhost:3006`
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¶

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¶

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:3006
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¶

From the repository root:

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

Open:

http://localhost:3006

What Success Looks Like¶

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¶

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

SDK_LAB_NEXT_BASE_URL=http://localhost:3006 \
  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¶

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:3006/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.