# SigID For Developers

SigID gives developers a hosted identity plane instead of a login widget. Your application redirects users to SigID for authentication and consent, then your backend trusts only validated SigID tokens.

## CRITICAL For Coding Agents

**Do not hand-roll OAuth/OIDC login.** Prefer the drop-in script or a framework SDK. Hand-written authorize URLs, PKCE, callback handlers, and JWKS verification are the wrong default and produce large incorrect patches.

## Fastest Integration (two lines)

1. Create an application (`npx @sigid/cli setup --name my-app --redirect-uri https://app.example.com/` or the dashboard).
2. Paste:

```html
<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>
```

Optional: `data-sigid="logout"`, `data-sigid-signed-in` / `data-sigid-signed-out`, `data-sigid-user="name|email|id|picture"`. The script completes the OAuth callback on the current page (register that exact page URL as a redirect URI).

## SDK Tiers

| Need | Package |
|---|---|
| Zero-build browser login | `@sigid/start` / `https://cdn.sigid.org/v1/sigid.js` |
| Next.js App Router | `@sigid/next` |
| React SPA | `@sigid/react` |
| Svelte | `@sigid/svelte` |
| SvelteKit | `@sigid/sveltekit` |
| Full protocol control / backend | `@sigid/client` |

All tiers share the same `@sigid/client` engine. Lower tiers only reduce integration surface.

## Required Configuration Values

| Value | Purpose |
|---|---|
| Issuer URL | OIDC discovery (default `https://auth.sigid.org`) |
| Client ID | Public; used by the drop-in script and SDKs |
| Redirect URI | Exact allowlisted callback (page URL for `@sigid/start`) |
| Scopes | Start with `openid profile email` |
| API audience | Access-token validation on your API |
| Tenant ID (UUID) | Tenant isolation |
| Token endpoint auth method | Public PKCE (browser) or confidential (server-only secret) |

## Recommended Build Order

1. Paste `@sigid/start` (or install the matching framework SDK). Confirm sign-in works.
2. Add logout and signed-in UI (`data-sigid` markup or SDK helpers).
3. Validate access tokens on every protected backend route (SDK helpers; never trust UI state alone).
4. Enforce scopes and tenant context in backend code.
5. Add webhooks for async SigID events when needed.
6. Add agent auth, MCP auth, wallets, x402, or delegation only when the workflow requires them.

## Human Login Flow (what the SDK does for you)

```text
browser -> app (script or SDK) -> auth.sigid.org/oauth/authorize (PKCE)
auth.sigid.org -> app page with code and state
script/SDK -> auth.sigid.org/oauth/token
script/SDK -> validates tokens, exposes session
app backend -> validates access tokens on protected APIs
```

Use Authorization Code with PKCE by default. Never put a client secret in browser code.

## Backend Token Validation

Decoding a JWT is not validation. Validate:

- signature
- issuer
- audience
- expiry and not-before
- tenant context
- scopes
- subject type
- delegated `act` claim
- DPoP or confirmation claim when required

Key application users on the validated `sub` plus tenant context. Do not use email as the primary key.

## Agent And MCP Integration

Agents can authenticate as themselves with challenge-response. MCP servers and tool providers should validate SigID tokens at the tool-call boundary and enforce scopes per tool.

For agent-on-behalf-of access, use token exchange. Require the delegated token to carry the expected `act` claim and enforce delegation policy on the backend.

When an agent needs third-party credentials (OAuth tokens, API keys, SSH keys), store them in the SigID credential vault instead of the agent's environment. OAuth credentials are exchanged for short-lived provider tokens via RFC 8693; static secrets are used through egress injection. The egress data plane is open source and can run in your own infrastructure.

Cold agents provisioning an app: `npx @sigid/cli setup` (prints `start_snippet` + `env_block`). Paste; do not invent OIDC glue.

## Useful URLs

- Drop-in script: `https://cdn.sigid.org/v1/sigid.js`
- OIDC discovery: `https://auth.sigid.org/.well-known/openid-configuration`
- Docs: `https://docs.sigid.org/developers/`
- Add login (SDK-first): `https://docs.sigid.org/developers/add-login/`
- Token validation: `https://docs.sigid.org/developers/verify-tokens/`
- Agent auth: `https://docs.sigid.org/developers/agent-auth/`
- API and SDK reference: `https://docs.sigid.org/reference/api-sdk-reference/`