# SigID Quickstart

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

## CRITICAL For Coding Agents

1. **Do not hand-roll OAuth/OIDC** (no custom authorize URLs, PKCE, callback routes, or JWKS verify for interactive login).
2. Run setup → paste the printed `@sigid/start` snippet (or framework SDK).
3. Only open the protocol reference if the user explicitly needs full protocol control.

## 1. Create An Application

### For agents building an app (autonomous, preferred)

```bash
npx @sigid/cli setup --name my-agent --redirect-uri http://localhost:3000/
# prints client_id, .env block, @sigid/start snippet, optional operator invite
npx @sigid/cli verify-setup
```

HTTP equivalent (auth issuer host):

1. `POST /api/v1/agents/workspace/bootstrap/pow` with agent key + ownership proof
2. Mine the PoW challenge
3. `POST /api/v1/agents/workspace/bootstrap/pow/complete` → agent, org, env, app, tokens, `start_snippet`, `env_block`
4. **Paste `start_snippet` into the app. Stop. Do not write OIDC code.**

### For humans (dashboard)

1. Sign up at `https://identity.sigid.org/`.
2. Open `https://dashboard.sigid.org/`.
3. Create organization → tenant environment → application.
4. Register exact redirect URIs (for the drop-in script: the page URL that hosts it).
5. Register allowed browser origins.
6. Copy client ID (and secret only if you use a confidential server-side client).

## 2. Add Hosted Login (two lines)

```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 UI:

```html
<div data-sigid-signed-out>
  <a href="#" data-sigid="login">Sign in</a>
  <a href="#" data-sigid="signup">Create account</a>
</div>
<div data-sigid-signed-in hidden>
  Hi, <span data-sigid-user="name"></span>
  <a href="#" data-sigid="logout">Sign out</a>
</div>
```

Framework apps: use `@sigid/next`, `@sigid/react`, `@sigid/svelte`, or `@sigid/sveltekit` instead of inventing glue. See [developers.md](https://www.sigid.org/developers.md).

## 3. Validate Access Tokens In Your API

Every protected backend route must validate (prefer SDK helpers from `@sigid/client` / framework packages):

- 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
- required scopes are present
- subject type is allowed
- delegated `act` claim when present

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

## 4. Agent Authentication (runtime)

After workspace bootstrap (step 1), agents authenticate with challenge-response:

1. `POST /api/v1/agents/auth/challenge`
2. Sign the canonical challenge payload
3. `POST /api/v1/agents/auth/verify` → bearer token
4. Validate agent tokens with the same rigor as human tokens

## 5. Read Next

- Drop-in script: `https://cdn.sigid.org/v1/sigid.js`
- `https://docs.sigid.org/developers/agent-quickstart.md`
- `https://docs.sigid.org/developers/add-login/`
- `https://docs.sigid.org/developers/verify-tokens/`
- `https://docs.sigid.org/reference/api-sdk-reference/`