# SigID Quickstart

This is the shortest correct path to use SigID in an application, backend API, or AI agent integration.

## 1. Create And Configure An Application

1. Sign up or sign in at `https://identity.sigid.org/`.
2. Open `https://dashboard.sigid.org/`.
3. Create or select an organization.
4. Create or select a tenant environment.
5. Create an application for the product users will open.
6. Register exact redirect URIs for local, staging, and production.
7. Register allowed browser origins for browser-based apps.
8. Choose OAuth grant types. Use Authorization Code with PKCE for interactive user login.
9. Choose scopes. Start with `openid profile email` and add API scopes only when needed.
10. Copy the issuer URL, client ID, redirect URI, API audience, tenant ID or slug, scopes, and token endpoint auth method into your app configuration.

## 2. Add Hosted Login

Redirect the user to SigID hosted auth. Resolve endpoints through OIDC discovery:

```text
GET https://auth.sigid.org/.well-known/openid-configuration
```

Build an authorization request:

```text
GET /oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback
  &scope=openid%20profile%20email
  &code_challenge=BASE64URL_SHA256_CODE_VERIFIER
  &code_challenge_method=S256
  &state=OPAQUE_CSRF_VALUE
```

Rules:

- Use the exact registered redirect URI.
- Generate a fresh `state` and PKCE verifier per login attempt.
- Store `state` and the verifier server-side or in storage bound to the browser interaction.
- Do not put client secrets in browser code.

## 3. Handle The Callback

On return to your application:

1. Verify the returned `state`.
2. Exchange the authorization code once at the discovered token endpoint.
3. Use the registered token endpoint authentication method.
4. Validate the returned ID token and access token.
5. Create an application session only after validation succeeds.
6. Do not log authorization codes, access tokens, refresh tokens, client secrets, or private keys.

## 4. Validate Access Tokens In Your API

Every protected backend route must validate:

- token signature against SigID JWKS
- `iss` equals the expected issuer
- `aud` equals the API audience
- `exp` and `nbf` are valid
- tenant or workspace context matches the routed tenant
- required scopes are present
- subject type is allowed for the operation
- delegated `act` claim is handled when present

Do not authorize by hidden frontend controls. Do not key users by email. Use the validated pairwise `sub` plus tenant context.

## 5. Add Agent Authentication When Needed

For autonomous agents:

1. Generate a supported signing key.
2. Register the agent with a public key, capabilities, scopes, and at least one anchor.
3. Prefer public proof-of-work registration when registering from the open internet.
4. Request a tenant-bound, single-use challenge.
5. Sign the canonical challenge payload with the registered private key.
6. Submit the signature for verification.
7. Use the returned agent-scoped token as a bearer token.
8. Validate agent tokens with the same rigor as human tokens.

For agents acting on behalf of a human or another agent, use RFC 8693 token exchange and require the delegated token to carry the expected `act` claim.

## 6. Read Next

- `https://docs.sigid.org/developers/quickstart-nextjs/`
- `https://docs.sigid.org/developers/add-login/`
- `https://docs.sigid.org/developers/verify-tokens/`
- `https://docs.sigid.org/developers/agent-auth/`
- `https://docs.sigid.org/developers/registration/`