API Auth and Error Model

Understand how authentication works across the 10x API, what errors you can expect, and how to handle them.

Auth modes

The API uses four authentication modes. The mode you need depends on the endpoint you are calling.

When to use JWT vs. PAT

Need concrete route-by-route guidance? See JWT vs PAT: When to Use Each.

JWT vs PAT in practice

Concrete examples

curl -sS "https://api.10x.in/v2/handles" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

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

curl -sS -X POST "https://api.10x.in/v2/handles/${HANDLE}/tokens" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-worker","scopes":["links.read","links.write"],"expiresInDays":30}'

JWT refresh behavior

POST /v2/auth/refresh uses the refresh cookie established at login. For browser clients, send requests with credentials: "include".

For CLI workflows, use a cookie jar:

curl -sS -c cookies.txt -X POST "https://api.10x.in/v2/auth/login" \
  -H "content-type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

curl -sS -b cookies.txt -c cookies.txt -X POST "https://api.10x.in/v2/auth/refresh" \
  -H "content-type: application/json"

Obtaining a JWT

curl -sS -X POST "https://api.10x.in/v2/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

{
  "email": "you@example.com",
  "password": "your-password"
}

Returns an access token. Include it in subsequent requests:

Authorization: Bearer <access-token>

JWTs expire after a set period. When you receive a 401 token_expired error, log in again to get a fresh token.

Obtaining a PAT

See API Tokens and Automations for creating and managing PATs.

Error model

Every error response follows a consistent structure:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have the required scope: analytics.*",
    "statusCode": 403
  }
}

Error categories

Retry policy

Follow these rules for reliable integrations:

Rate limits

The API enforces per-handle rate limits. Exact limits depend on your plan tier:

See Plans, Quotas, and Feature Gates for the full plan comparison.

Common integration patterns

    curl -sS "https://api.10x.in/v2/handles/{handle}/links/{slug}" \
      -H "Authorization: Bearer <access-token>"

    curl -sS -X PUT "https://api.10x.in/v2/handles/{handle}/links/{slug}" \
      -H "Authorization: Bearer <access-token>" \
      -H "Content-Type: application/json" \
      -d '{"destinationUrl": "https://example.com/product", "title": "Product Page"}'

    curl -sS -X POST "https://api.10x.in/v2/public/conversions" \
      -H "Content-Type: application/json" \
      -d '{"ctx": "...", "eventType": "purchase", "value": 49.99, "idempotencyKey": "order-12345"}'

    {
      "ctx": "...",
      "eventType": "purchase",
      "value": 49.99,
      "idempotencyKey": "order-12345"
    }

Related