# 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.

## Required Configuration Values

Collect these before writing code:

| Value | Purpose |
|---|---|
| Issuer URL | OIDC discovery, authorization, token exchange, JWKS |
| Client ID | Authorization requests |
| Redirect URI | Callback allowlist and code exchange |
| Scopes | Consent and API authorization |
| API audience | Access-token validation |
| Tenant ID or slug | Tenant isolation and support |
| Token endpoint auth method | Public PKCE or confidential client exchange |
| Test account | End-to-end login and policy testing |

## Recommended Build Order

1. Add hosted login with Authorization Code and PKCE.
2. Handle the OAuth callback and error callback.
3. Create an application session after token validation.
4. Add logout and token revocation where the product needs it.
5. Validate access tokens on every protected backend route.
6. Enforce scopes and tenant context in backend code.
7. Add webhooks for async SigID events.
8. Add agent auth, MCP auth, wallets, x402, or delegation only when the workflow requires them.

## Human Login Flow

```text
browser -> app -> auth.sigid.org/oauth/authorize
auth.sigid.org -> app callback with code and state
app backend -> auth.sigid.org/oauth/token
app backend -> validates tokens against discovery and JWKS
app backend -> creates app-local session
```

Use Authorization Code with PKCE by default. Browser-only, mobile, desktop, and CLI apps are public clients. Web apps with trusted backends may use a confidential client auth method, but the secret stays server-side only.

## 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 by the application

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.

## Useful URLs

- OIDC discovery: `https://auth.sigid.org/.well-known/openid-configuration`
- Docs: `https://docs.sigid.org/developers/`
- OAuth/OIDC reference: `https://docs.sigid.org/reference/oauth-oidc/`
- Token validation guide: `https://docs.sigid.org/developers/verify-tokens/`
- Agent auth guide: `https://docs.sigid.org/developers/agent-auth/`
- API and SDK reference: `https://docs.sigid.org/reference/api-sdk-reference/`