# KardMesh auth.md

> Authentication, registration, and API access guide for AI agents, automated pipelines, and 3D software addons (Blender).

## Discovery Endpoints

- **OAuth Protected Resource Metadata**: https://kardmesh.com/.well-known/oauth-protected-resource
- **OAuth Authorization Server Metadata**: https://kardmesh.com/.well-known/oauth-authorization-server
- **OpenID Connect Discovery**: https://kardmesh.com/.well-known/openid-configuration
- **JWKS**: https://kardmesh.com/.well-known/jwks.json

## Audience

This document applies to:
- AI coding and commerce agents integrating KardMesh 2D-to-3D hair generation
- Official 3D software addons (Blender) authenticating with personal API keys
- Headless clients submitting pay-per-variation jobs via x402

## Supported Authentication & Registration Methods

1. **Passwordless Email Magic Link (User Account & Welcome Credits)**
   - Endpoint: POST https://api.kardmesh.com/auth/sign-in/magic-link
   - Claim / Welcome URL: https://kardmesh.com/welcome
   - Payload: `{ "email": "user@example.com", "callbackURL": "https://kardmesh.com/welcome" }`
   - Verification: GET https://api.kardmesh.com/auth/magic-link/verify
   - Grants a web session cookie and **5 free non-expiring welcome credits**.

2. **Personal Addon API Keys (Bearer / Header Token)**
   - Provisioning (authenticated session): POST https://api.kardmesh.com/account/api-keys
   - Usage: send `Authorization: Bearer <api_key>` or `x-api-key: <api_key>` on requests to `/jobs`, `/jobs/{id}/status`, and `/jobs/{id}`.
   - Keys are stored hashed (SHA-256) and can be revoked anytime via DELETE https://api.kardmesh.com/account/api-keys/{id}.

3. **Anonymous Guest Trial**
   - Check allowance: GET https://api.kardmesh.com/jobs/guest-trial
   - Submit up to 2 free trial generations (1 variation each) by sending `x-guest-token` and Cloudflare Turnstile verification.

4. **x402 Agent-Native HTTP Payments**
   - Endpoint: POST https://api.kardmesh.com/x402/jobs
   - No account required: unauthenticated requests receive HTTP `402 Payment Required` with `PAYMENT-REQUIRED` metadata; retry with `PAYMENT-SIGNATURE` to pay per variation in USDC on Base.