JWT vs PAT: When to Use Each

Use this guide when you need a clear answer to: "Should this call use JWT or PAT?"

Quick answer

JWT vs PAT comparison

Route boundary rules

JWT-first examples

• POST /v2/handles/{handle}/tokens (create PAT)
• PUT /v2/handles/{handle}/skills/{skillKey} (update hosted skill metadata)
• PUT /v2/handles/{handle}/skills/{skillKey}/runtime (configure hosted skill runtime)
• POST /v2/handles/{handle}/skills/{skillKey}/publish (publish hosted skill version)
• PUT /v2/handles/{handle}/collaborators
• POST /v2/billing/checkout-session
• POST /v2/account/domains

PAT-first examples

• GET /v2/public/handles/{handle}/links
• PUT /v2/public/handles/{handle}/links/{slug}
• GET /v2/public/handles/{handle}/analytics
• POST /v2/public/handles/{handle}/webhooks

Important exceptions

Most PAT usage is on /v2/public/handles/{handle}/*, but selected handle-scoped agent/QA endpoints also allow PAT when documented with PAT scopes. Treat PAT support as endpoint-specific, not automatic.

Hosted skill writes under /v2/handles/{handle}/skills/* are JWT control-plane routes. Use JWT Skill Management for the exact skill update, runtime, publish, and delete contract.

Use API Endpoint Coverage Map to confirm auth mode for a specific route.

How JWT session refresh works

JWT login returns token payload fields and sets an HttpOnly refresh cookie. Refresh uses that cookie via POST /v2/auth/refresh.

Implementation detail: the refresh cookie key is _10x_admin_refresh and the session cookie is managed as HttpOnly; Secure; SameSite=Lax.

Browser pattern

const refreshed = await fetch("https://ai.10x.in/v2/auth/refresh", {
  method: "POST",
  headers: { "content-type": "application/json" },
  credentials: "include",
});

cURL pattern (cookie jar)

# 1) Login and save cookies (includes refresh cookie)
curl -sS -c cookies.txt -X POST "https://ai.10x.in/v2/auth/login" \
  -H "content-type: application/json" \
  -d '{"email":"owner@example.com","password":"<password>"}'

# 2) Refresh using saved refresh cookie
curl -sS -b cookies.txt -c cookies.txt -X POST "https://ai.10x.in/v2/auth/refresh" \
  -H "content-type: application/json"

If the refresh cookie is missing or invalid, expect 401 refresh_token_missing or 401 invalid_refresh_token.

How PAT lifecycle works

PATs are created via JWT-authenticated control-plane routes, then used for automation calls.

Implementation detail: when both x-api-key and Authorization are present, PAT parsing prioritizes x-api-key.

Bootstrap PAT with JWT

curl -sS -X POST "https://ai.10x.in/v2/handles/${HANDLE}/tokens" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H "content-type: application/json" \
  -d '{
    "name": "ci-links",
    "scopes": ["links.read","links.write","analytics.read"],
    "expiresInDays": 30
  }'

Use PAT in automation

curl -sS "https://ai.10x.in/v2/public/handles/${HANDLE}/links" \
  -H "x-api-key: ${PAT_TOKEN}"

PAT auth guardrails are rate-limited per minute both by (handle + tokenId + source IP) and by handle burst limits.

Error behavior when token type is wrong

Recommended usage patterns

1. Use JWT to bootstrap control-plane setup

   Sign in, create/update handle resources, and mint scoped PATs.

2. Use PAT for unattended jobs

   Run CI/CD, scheduled tasks, webhook workers, and backend integrations with least-privilege scopes.

3. Rotate PATs deliberately

   Use one PAT per system, rotate regularly, and revoke old tokens immediately after cutover.

4. Do not put JWTs in long-running automation

   JWTs are session-oriented and expire; use PATs for durable service credentials.

Copy-paste decision checklist

1. Does this endpoint live under control-plane families (/v2/handles/, /v2/account/domains/, /v2/billing/*, admin/operator)? Use JWT.
2. Is this an automation endpoint that explicitly supports PAT scopes? Use PAT.
3. Need cross-handle user context? Use JWT.
4. Need one handle + least privilege + unattended execution? Use PAT.
5. Not sure? Check API Endpoint Coverage Map first.

Related

• API Tokens and Automations
• JWT Skill Management
• API Auth and Error Model
• API Endpoint Coverage Map
• Troubleshooting and Support