API Tokens and Automations

Create and manage Personal Access Tokens (PATs) for programmatic access to your handle's data and operations.

Need help deciding between PAT and JWT for a specific endpoint? Start with JWT vs PAT: When to Use Each.

Key concepts

Available scopes

Create a PAT

Using a PAT

Include the PAT in the Authorization header:

Authorization: Bearer patv1_<tokenId>.<secret>

Or, where supported, use the x-api-key header:

x-api-key: patv1_<tokenId>.<secret>

Examples

curl -sS "https://ai.10x.in/v2/public/handles/acme/links" \
  -H "Authorization: Bearer patv1_abc123.secret456"

curl -sS "https://ai.10x.in/v2/public/handles/acme/analytics?funnel=true" \
  -H "Authorization: Bearer patv1_abc123.secret456"

curl -sS "https://ai.10x.in/v2/public/handles/acme/analytics?groupBy=ai_referrer" \
  -H "Authorization: Bearer patv1_abc123.secret456"

curl -sS -X PUT "https://ai.10x.in/v2/public/handles/acme/links/new-launch" \
  -H "Authorization: Bearer patv1_abc123.secret456" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl":"https://example.com/launch","title":"New Launch"}'

Manage tokens

List all tokens

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

Returns all active tokens for the handle (without secrets).

Revoke a token

curl -sS -X DELETE "https://ai.10x.in/v2/handles/{handle}/tokens/{tokenId}" \
  -H "Authorization: Bearer <access-token>"

Required auth

• OPERATOR-level JWT or above to create, list, and revoke tokens.
• The PAT itself authenticates requests on /v2/public/handles/{handle}/* routes.

When PAT is not enough

Use JWT (not PAT) for control-plane actions such as:

• collaborator management
• billing and checkout-session management
• account-domain operations
• PAT lifecycle endpoints themselves (/v2/handles/{handle}/tokens*)

If you send a PAT to a JWT-only endpoint, expect a role/scope-style auth failure (commonly 403 insufficient_scope).

PAT-accessible endpoints

Webhook note: /v2/public/handles/{handle}/webhooks/{subscriptionId}/test returns 202 when the delivery is queued. Your automation should still verify sink logs or downstream status before treating the test as successful.

Context Store refresh note: Webhook receivers and external automations can call the MCP sync route after verifying an event. This requests an async refresh; it does not ingest webhook payloads directly into Context Store.

Best practices

1. One token per system

   Give your CI pipeline one token, your dashboard another, and your webhook processor a third. If one is compromised, you can revoke it without affecting the others.

2. Minimal scopes

   A dashboard that only reads analytics should not have links.write.

3. Never commit secrets

   Store PATs in environment variables or a secrets manager. Never hardcode them in source files.

4. Rotate regularly

   Create a new token, update your systems, then revoke the old one.

Common errors

| Code | Error | Cause | |---|---|---| | 401 | missing_bearer_token | No Authorization header provided | | 401 | invalid_token | Token format is wrong or the secret does not match | | 403 | insufficient_scope | Token does not have the required scope for this endpoint | | 403 | insufficient_role | Caller does not have OPERATOR or higher role to manage tokens | | 404 | not_found | Token does not exist (already revoked or never created) |

Related