# auth.md

This document tells AI agents how to obtain credentials for **ForgeKit** (`https://useforgekit.dev`).

ForgeKit is a developer utility API (screenshots, PDFs, OG images, QR codes, link previews, JSON validation, ShipPack/ShipVerify, deterministic compute, and MCP). Agents that call the REST API or MCP need an API key, or they can pay per request with x402 USDC on Base (all product routes).

There is **no** `POST /agent/auth` registration API and **no** OAuth access-token issuer. Registration is browser GitHub OAuth; credentials are `fk_live_` API keys.

## Discover

1. Call any protected API route without credentials. The response is `401` with:

   ```
   WWW-Authenticate: Bearer FAKESECRET_g3h4i5j6k7l8m9n0o1p2="https://useforgekit.dev/.well-known/oauth-protected-resource"
   ```

2. Fetch Protected Resource Metadata (RFC 9728) at that URL (or the conventional path `/.well-known/oauth-protected-resource`). Read `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.

3. Fetch Authorization Server metadata from `{authorization_servers[0]}/.well-known/oauth-authorization-server`. Read `issuer` and the `agent_auth` block (`skill`, `register_uri`, `claim_uri`, identity / credential types).

4. Or start here: `GET https://useforgekit.dev/auth.md` (this file). If anything conflicts, prefer the PRM and AS metadata.

## Register

**Method:** verified email via GitHub OAuth (human-in-the-browser).

1. Open `https://useforgekit.dev/signup` (or `https://useforgekit.dev/login` if the user already has an account).
2. Complete GitHub OAuth. ForgeKit uses the verified GitHub email; a signup trust gate may withhold free credits for throwaway accounts.
3. After session cookies are set, mint an API key (see Provision).

Agents cannot complete this step without a human. Do not probe `POST /agent/auth` - it does not exist.

## Provision

With a logged-in browser session:

```http
POST https://useforgekit.dev/api/keys
Content-Type: application/json

{"name":"Default"}
```

Success returns a one-time secret `key` (`fk_live_...`). Store it securely; only the prefix is shown again later.

Dashboard UI: `https://useforgekit.dev/dashboard`.

## Use the credential

Send the API key as a Bearer token:

```http
Authorization: Bearer fk_live_...
```

`scopes_supported` is `["api"]` - keys are not operation-scoped. Rate limits and starter credits apply per account.

Docs: `https://useforgekit.dev/docs` · OpenAPI: `https://useforgekit.dev/openapi.json` · MCP: `https://useforgekit.dev/mcp`

## Alternate: x402 (no account)

All product `/api/v1/*` routes accept HTTP 402 / x402 payments (USDC on Base, `eip155:8453`) without an API key. Unauthenticated calls return payment requirements; settle with `PAYMENT-SIGNATURE`. API keys still work for credit metering. See `/.well-known/agent.json` for the price table.

## What is not supported

- `POST /agent/auth` or automated agent registration endpoints
- ID-JAG / JWT-bearer OAuth token exchange
- Anonymous API key issuance
- OAuth `access_token` / `refresh_token` for the REST API

Revoke keys from the dashboard or `DELETE` via the keys API when authenticated with a session.