# auth.md

How AI agents authenticate with Skillmonger, the marketplace that routes
high-stakes questions to verified human experts.

There are three ways in, depending on what kind of agent you are. Full API
reference: https://api.skillmonger.ai/llms.txt

## Agent registration

**Audience:** any AI agent: connected apps acting for a human user, or
autonomous agents paying with a wallet. No pre-approval, no waitlist.

- **Registration endpoint:** `POST https://api.skillmonger.ai/oauth/register`
  (Dynamic Client Registration, RFC 7591)
- **Registration methods supported:** `dynamic_client_registration`
- **Identity types supported:** `anonymous` (register without credentials;
  the human user's identity is verified later, in the consent flow, via
  email magic link)
- **Credential types issued:** OAuth 2.1 Bearer access token + refresh
  token, obtained through the PKCE authorization-code flow (`S256` only,
  no client secret)
- **Revocation:** `POST https://api.skillmonger.ai/oauth/revoke`
- **Discovery:** this file is referenced from the `agent_auth` block in
  `https://api.skillmonger.ai/.well-known/oauth-authorization-server`

Agents that don't want an account at all can skip registration entirely;
see the x402 wallet path (§2) and per-request tokens (§3) below.

## 1. Connected app (OAuth 2.1 + hosted MCP): recommended

For agents acting on behalf of a human user (Claude, ChatGPT, Cursor, custom
MCP clients). PKCE-only, no client secret.

1. **Discover.** `GET https://api.skillmonger.ai/.well-known/oauth-authorization-server`
2. **Register.** `POST https://api.skillmonger.ai/oauth/register` (RFC 7591
   Dynamic Client Registration, anonymous; no pre-approval needed):

   ```json
   {
     "client_name": "Your Agent",
     "redirect_uris": ["https://your-app.example/callback"],
     "scope": "mcp",
     "token_endpoint_auth_method": "none"
   }
   ```

3. **Authorize.** Send the user to `/oauth/authorize` with PKCE
   (`code_challenge_method=S256`). The user approves on our consent page and
   verifies their email via a one-time sign-in link. That email is where
   expert answers are delivered.
4. **Exchange.** `POST /oauth/token` with the auth code + `code_verifier` →
   access token (+ refresh token).
5. **Use.** MCP endpoint: `https://api.skillmonger.ai/mcp` (streamable
   HTTP, `Authorization: Bearer <token>`). Tools: `ask_an_expert`,
   `get_approval_url`, `check_request`, `get_deliverables`, `upload_file`,
   `review_response`, `list_my_requests`, `ask_follow_up`.

## 2. Autonomous agent (x402 / USDC on Base): no account at all

Pay per request; your wallet is your identity.

1. `POST https://api.skillmonger.ai/requests/submit` with no payment header
   → HTTP 402 with USDC payment requirements.
2. Sign with your wallet, retry with the `PAYMENT-SIGNATURE` header → 200
   with `request_id` + a signed access URL.
3. Read your own requests anytime: `GET /requests/mine` with an EIP-191
   signature of `skillmonger:requests-mine:{address}:{timestamp}` in
   `X-Wallet-Signature` (+ `X-Wallet-Timestamp`, 300s window).

## 3. Per-request access token: no auth setup

Every submitted request returns URLs carrying a signed `?t=<token>` scoped
to that single request (also accepted as `X-Request-Token` header). Keep it;
it is the only credential you need to poll status and fetch deliverables
for that request.

## Notes

- No API keys, no passwords, no JWTs handed to users.
- Payments are always explicitly approved: humans approve on the website;
  x402 agents sign each payment.
- Rate limits and full schemas: https://api.skillmonger.ai/llms.txt