links.10x.in/docs/end-user/playbooks/onboarding-and-api-primer Published:

Onboarding and API Primer

Last updated: 2026-03-26

This primer is the API setup baseline used by all playbooks.

1. Environment bootstrap

export PUBLIC_DOMAIN="10x.in"
export API_BASE="https://ai.10x.in"
export CONNECT_BASE="https://login.connect.10x.in"
export PROFILE_BASE="https://profile.${PUBLIC_DOMAIN}"
export APP_BASE="https://app.${PUBLIC_DOMAIN}"
export HANDLE="your-handle"

2. Auth modes and where they apply

  1. JWT: signed-in control-plane routes (/v2/handles/*, /v2/account/domains/*, /v2/platform-admin/*, /v2/operator/*).
  2. PAT: non-MCP automation routes (/v2/public/handles/{handle}/*) and selected integration surfaces.
  3. VISITOR_COOKIE: checkout/access/purchase visitor lifecycle.
  4. OAUTH_CONNECTOR: hosted MCP connector authentication for https://{handle}.mcp.10x.in/mcp (compat: https://ai.10x.in/mcp/{handle}/mcp).
  5. NONE: public routes such as /v2/public/context, /v2/public/conversions, /v2/public/chain/*.
  6. OPENANALYST_SESSION: JWT-backed product-session resolution through /v2/account/openanalyst/me after browser auth on ${APP_BASE}.

Smartwork/OpenAnalyst host boundary

  • open the browser UI from ${APP_BASE}
  • expect sign-in handoff through ${CONNECT_BASE}
  • use ${API_BASE} for GET /v2/account/openanalyst/me and desktop auth endpoints
  • do not use handle hosts as management or launch entrypoints

3. Obtain JWT and PAT

JWT login

curl -sS -X POST "${API_BASE}/v2/auth/login" \
  -H 'content-type: application/json' \
  -d '{"email":"owner@example.com","password":"<password>"}'
export JWT_TOKEN="<paste-access-token>"

PAT creation

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/tokens" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"name":"playbook-token","scopes":["analytics.*","webhooks.*","tracking.templates.*"]}'
export PAT_TOKEN="patv1_<tokenId>.<secret>"

Smartwork/OpenAnalyst session check

For Smartwork/OpenAnalyst-enabled users, confirm the browser-backed session resolves product access:

curl -sS "${API_BASE}/v2/account/openanalyst/me" \
  -H "authorization: Bearer ${JWT_TOKEN}"

Expected baseline:

  1. 200 OK for authenticated users with OpenAnalyst entitlement.
  2. 401 if the JWT/session is missing or expired.
  3. Desktop pairing should start from the app or desktop shell and complete in the browser, not through a local password prompt.

4. Baseline verification calls (required)

curl -sS "${API_BASE}/v2/handles" \
  -H "authorization: Bearer ${JWT_TOKEN}"
curl -sS "${API_BASE}/v2/public/handles/${HANDLE}/links" \
  -H "authorization: Bearer ${PAT_TOKEN}"

Expected baseline:

  1. 200 OK on both routes.
  2. JWT and PAT are both valid for their intended route families.

5. Standard placeholders reused in playbooks

  • PUBLIC_DOMAIN, API_BASE, HANDLE
  • JWT_TOKEN, PAT_TOKEN
  • VISITOR_COOKIE
  • OAUTH_CONNECTOR (MCP connector auth context)
  • SLUG, CAMPAIGN_ID, RULE_ID, DOMAIN_NAME, PAGE_SLUG, RUN_ID

6. Error model quick-reference

Common deterministic failures:

  • 401 missing_bearer_token|invalid_token|token_expired
  • 403 insufficient_scope|insufficient_role|feature_locked
  • 404 not_found
  • 409 conflict
  • 429 rate_limited

Retry policy:

  1. Retry only 429 and selected 5xx with backoff.
  2. Never blindly retry auth/scope/validation failures.

7. Route boundary reminder

OpenAPI covers public/admin /v2 routes only, excluding:

  • /_edge/*
  • /mcp/*
  • hosted MCP connector URLs (https://{handle}.mcp.10x.in/mcp, https://ai.10x.in/mcp/{handle}/mcp)
  • /profiles/*

Role-gated operation steps are support-mediated in public docs:

8. Next step

  1. Use Playbooks Index to pick a role-appropriate module.
  2. For token/error behavior details, read API Auth and Error Model.