Skip to main content

​
API keys (Public Metrics API)

The versioned /api/v1/* endpoints on the web app authenticate with long-lived Ansvisor API keys (prefix ans_), created under Settings → MCP & API Keys in the dashboard:
This is the right choice for external integrations — Looker Studio, Sheets, scripts, and the MCP server. See the Metrics API reference for the endpoint list.

​
App sign-in (OAuth) for the MCP server

AI apps such as Claude and ChatGPT can connect to the MCP endpoint, https://app.ansvisor.com/api/mcp, by signing the person in instead of with an API key. The web app is the authorization server (OAuth 2.1 with PKCE S256, as the MCP authorization spec 2025-11-25 has it), with the issuer https://app.ansvisor.com:
  • An app finds it from the endpoint’s 401 (WWW-Authenticate: Bearer resource_metadata="https://app.ansvisor.com/.well-known/oauth-protected-resource/api/mcp", scope="mcp:read mcp:write"), then /.well-known/oauth-authorization-server.
  • It registers with a Client ID Metadata Document or by dynamic client registration (POST /api/oauth/register), sends the person to /api/oauth/authorize, and redeems the code at /api/oauth/token.
  • Scopes: mcp:read (every list_ and get_ tool) and mcp:write (every other tool), which the person can leave out on the consent page.
  • Access tokens (ans_oat_…) last an hour. Refresh tokens (ans_ort_…) last 30 days and rotate on every use. Both are bound to the MCP endpoint (RFC 8707 resource).
  • A token acts as the person who allowed it, with their role and brand access. They see and disconnect it in Settings → MCP & API Keys → Connected apps; an app revokes its own at /api/oauth/revoke (RFC 7009).
These tokens work at /api/mcp only. The Metrics API (/api/v1/*), the REST routes under /api/mcp/… and the server’s /api/* refuse them with 401. On Ansvisor Cloud, app sign-in needs a paid plan; API keys work on every plan. The MCP server guide has the full flow, lifetimes and errors.

​
Bearer token

All /api/* endpoints on the Ansvisor server require a Supabase JWT bearer token in the Authorization header:

​
Getting a token

The cleanest way is via the Supabase JS client in your own backend code:
The web app does this automatically — every server action and fetch attaches the current session token transparently.

​
Cron endpoints

A handful of internal endpoints under /api/internal/* (used by Vercel Cron and the Stripe success callback) authenticate via a shared CRON_SECRET instead of user tokens:
The same secret must be configured on both sides (Vercel env + server env).

​
Public endpoints

Three endpoints don’t require any auth:
  • GET /t.js — tracking pixel script
  • POST /track/{trackingCode} — tracking pixel beacon (the tracking code identifies the brand; rate-limited)
  • GET / — basic uptime check, returns { "status": "ok", "service": "aeo-server", "mode": "cloud" | "self-hosted", "timestamp": "..." }
The /api/health endpoint IS auth-protected — by design, it returns the authenticated user’s ID. For uptime monitoring, use GET / instead.

Continue: Brands API

CRUD endpoints for managing brands programmatically.