Integrate SigID Into A Third-Party App¶

Use this page when an AI agent or human is integrating SigID into another product (SaaS, agent, CLI, or API). It is the ordered checklist; deep pages carry the exact steps.

Decision Tree¶

Need interactive human login?
  Browser app / SPA / no existing server session?
    → Prefer drop-in script or framework SDK (below). Do not hand-roll OIDC for the browser.
  Confidential server with its own session (B2B SaaS, existing cookie auth)?
    → Prefer @sigid/backend (confidential code exchange, ID-token verification,
      RP-initiated logout, webhooks). See "Login For A Confidential Server /
      Existing Session" below.
  Backend API only (no interactive login)?
    → verify-tokens + protect-apis
  Autonomous agent?
    → agent-quickstart

Need to sell paid access?
  yes → commerce.md (payment links + webhooks). Not identity billing entitlements.

Need async events (membership, payment, security)?
  yes → webhooks.md + webhook-events.md (suite sigid-webhook-v1)

Login For A Confidential Server / Existing Session¶

Many real apps already run a confidential server with their own session store (B2B SaaS, server-rendered apps, an existing cookie/auth boundary that must stay authoritative). The recommended path is the @sigid/backend SDK (Backend SDK For Confidential Servers), which removes the footguns of hand-rolling – PKCE/state/nonce handling, confidential code exchange, JWKS caching, ID-token verification, and RP-initiated logout.

Use the backend SDK guide for the complete sequence: bind the login transaction to the initiating browser, exchange the code, verify the ID token, and establish your app's session. The ID token audience is the OAuth client ID; an API access token has the resource audience. Verify access tokens when calling a protected API, and keep application authorization checks in your backend.

For another server language, use a maintained OAuth/OIDC implementation and discovery. Keep client authentication, PKCE, state, nonce, and exact redirect checks. Being a server does not automatically make a public OAuth registration confidential.

Logout must clear your application session. RP-initiated logout ends the hosted session; token revocation is a separate operation. Follow the backend SDK's logout section for the ID-token hint and registered post-logout destination.

Configuration Handoff¶

Use Integration Settings to resolve the following values from one environment.

Cold agent without a human-precreated app:

npx @sigid/cli setup --name my-app --redirect-uri http://localhost:5173/auth/callback

Paste start_snippet and env_block from the output. Sandbox orgs have activation limits until a human co-owner activates production features.

Testing hosted end-user login: cold setup / workspace bootstrap returns fixture_end_user – ordinary human @test.sigid.dev + once-only password on the sandbox environment (outbound mail to that domain is suppressed). Run the app’s authorize round trip with those credentials. Agents are not end-user stand-ins. More users: signup, invite, or AAL2 admin create. Fixture is retired when the sandbox org is activated.

2. Choose The Login Package¶

Integration layers: start → framework adapter → @sigid/client for full protocol control. Framework packages wrap the client for SSR/cookies; they do not replace the drop-in script’s “two-line HTML” path. Use start when you only need browser login UI without a build.

<script src="https://cdn.sigid.org/v1/sigid.js"
  data-client-id="YOUR_CLIENT_ID"
  data-issuer="https://auth.sigid.org"></script>
<a href="#" data-sigid="login">Sign in</a>

3. Backend Token Validation¶

After login, APIs must validate the access token:

• signature (JWKS from discovery)
• iss, aud, exp / nbf
• tenant_id (or your deployment’s tenant claim)
• required scope
• allowed subject_type (human, agent, …)
• for delegated agents: act chain

See Verify Access Tokens and Protect Backend APIs.

4. OpenAPI (What Is Public)¶

Do not expect production to expose control-plane, billing admin, or full commerce manage schemas. For commerce integration paths, use Sell Access With SigID Commerce and the workflow specs.

Discovery remains always public:

GET {issuer}/.well-known/openid-configuration

Authorize endpoint is /oauth/authorize (not bare /authorize). Prefer the SDK so you never hard-code it.

Programmatic OpenAPI Access¶

Fetch the public document with your normal HTTP client and TLS verification. The committed OpenAPI documents are the canonical versioned API contract. The docs mirror publishes the committed public document. The issuer, committed documents and docs mirror must match the released version; repository tests check the generated contract.

Repository operators can compare curl and Python urllib without credentials:

python3 scripts/check-public-metadata.py --issuer https://auth.sigid.org \
  --ca-file /etc/ssl/certs/ca-certificates.crt

The command records status, JSON validity, content type and request/edge IDs, and exits unsuccessfully when either client cannot read the public document. Use the host's trusted CA bundle if Python lacks a configured bundle; never disable certificate verification. A 403 with an edge identifier and no SigID request ID needs correlation in the edge logs. Operators should correct the specific public-document rule if it blocks ordinary clients, preserving authentication and rate protections on other routes. Do not assume every HTTP client failure is an OAuth credential problem.

Browser Access Matrix¶

“Public” means no application credential is required; it does not imply every endpoint supports browser JavaScript from arbitrary origins.

Allowed Origins is separate from redirect URI registration. Adding an origin does not make every /api/v1/* endpoint callable from that browser. A dummy SPA can read metadata directly and initiate hosted login once it has an app; its server or coding agent performs proof-based provisioning. Keep private keys and management credentials out of the browser.

5. Webhooks¶

1. HTTPS receiver
2. Dashboard subscription + signing secret
3. Verify suite sigid-webhook-v1 (HKDF-HMAC, timestamp, max-age, delivery id)
4. Idempotent handling

See Receive Webhooks.

6. Commerce (Optional)¶

If you sell access: payment link → public /pay/{token} → webhook grant in your DB. Details: Sell Access With SigID Commerce.

7. Agents And MCP¶

• Human-delegated tools: Agent And MCP Auth
• Cold autonomous agent: Agent Self-Serve Quickstart

Package Reality Check¶

Published / in-repo today: @sigid/start, @sigid/client, @sigid/react, @sigid/next, @sigid/svelte, @sigid/sveltekit, @sigid/backend, @sigid/cli, plus Go/Rust/Elixir under sdks/.

Do not invent: @sigid/vue, @sigid/solid, @sigid/solidstart, @sigid/expo, @sigid/electron – they are not shipping packages. Use @sigid/client or start until a first-party adapter exists.

Done When¶

• Sign-in works: drop-in script/SDK for browser apps, or authorization-code+PKCE for confidential servers
• Logout clears app session
• Backend rejects invalid/missing tokens
• Redirect URI exact-match in Dashboard
• Webhooks verified if subscribed
• Commerce grants only after verified payment events (if selling)
• Secrets never logged or shipped to the browser

Next Pages¶