1. Winvariant
  2. Docs
  3. Authentication
Docs

Authentication

An API key for scripts and agents, a claim link for an agent that starts with nothing, and a sign-in screen for assistants. All three reach the same tools.

Docs: Quickstart · Authentication · Tool reference · Errors · Limits · What stays human · The skill

Three ways in

WayForHow
API keyA script, or an agent that can't open a sign-in screenThe owner makes it on their account page. Send Authorization: Bearer <key> to the HTTP API or to the connector.
Start without a keyAn agent whose person has no key yet, or no account yetPOST https://winvariant.com/api/v1/start, hand your person the link, poll for the key.
Sign-in on the connectorAn assistant with a sign-in screen (a chat app, an editor)Paste https://winvariant.com/mcp; the person logs in and allows it. See /agents.

All three reach the same tools, with the same permissions, limits and log.

API keys

  • Made on the account page (https://winvariant.com/account → API keys) with a name, the permissions, the businesses (all, or the ones picked) and an optional end date. An account can have 20.
  • A key starts with wv_live_. It is shown once, when it is made. We keep only a fingerprint of it, so nobody can show it again: a lost key is revoked and a new one made.
  • Revoke stops it at once. A key past its end date stops by itself. Deleting the account removes its keys.
  • A key acts only on businesses its owner owns now and picked for it. It never has more rights than its owner, and never staff rights.
  • Keep it in an environment variable (WINVARIANT_TOKEN). Never put it in a prompt, a chat, a log or a repository.
export WINVARIANT_TOKEN="wv_live_…"

# plain HTTP
curl -s https://winvariant.com/api/v1/tools/list_businesses \
  -H "Authorization: Bearer $WINVARIANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# the connector, without the sign-in
curl -s https://winvariant.com/mcp \
  -H "Authorization: Bearer $WINVARIANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Permissions

A key or a connection carries permissions, chosen by the owner. A tool needs exactly one:

PermissionWhat it allowsTools
read (always)See your businesses. Read your ads, your results, what is connected, what the system has learned about your account and what your plan has left, but never who your leads are.list_businesses, get_results, list_ads, ads_waiting_for_review, agent_activity, where_ads_work_best, lead_counts, plan_and_usage, connection_status, brain_read, read_account, best_ads, why_it_wins, list_campaigns, get_guardrails, activity, credits_and_plan, get_checkout_link, competitors, competitor_ads, suggest_from_competitors, brand_kit_read
reviewReview your ads. Approve or reject new ads with your decision, undo that, pass on a note in your own words, and switch a live ad off.review_ad, undo_review, add_note, switch_ad_off, brain_note, add_competitor, remove_competitor
createMake new ads. Add a business from its website, start new ads and write copy variants of one of your best ads, each time after telling you what that uses and getting your yes.make_new_ads, create_business, get_connect_link, propose_variants, propose_creative_variants, make_ad_from_own_video, brand_kit_describe, brand_kit_propose, brand_kit_accept
launchPut ads live. Change things in your ad account, each after your yes: work in an ad set you choose, add variants you approved there (always paused), pause an ad or switch one on, undo a change, and switch autopilot on or off. Always inside the limits you set.set_autopilot, adopt_campaign, add_to_campaign, pause_ad, resume_ad, undo_action, add_creative_to_ad_set
budgetChange budgets. Change a daily budget inside the spend cap you set, and set or lower that cap; raising or removing a cap stays with you.change_budget, set_guardrails
billingPrepare payments. Set your monthly limit on extra usage after you said yes to the most it can cost; paying in secure checkout is always done by you, never by the assistant.set_extra_usage_limit

A call beyond the key's permissions answers forbidden_scope. A key's permissions can't be widened: the owner makes a new key. Only permissions that a tool uses today are offered; more appear here when their tools do.

Start without a key

For an agent that begins with nothing. No key is issued until a person has logged in and pressed Allow.

  1. POST https://winvariant.com/api/v1/start with an optional { "name", "scopes" }. The answer is { claimUrl, pollToken, expiresAt }. Nothing has been issued.
  2. Give claimUrl to your person and say what it is. They log in to Winvariant, or make their account there with an email code or Facebook, read what you ask for, untick what they don't want, and press Allow or Deny. The link works for 30 minutes.
  3. POST https://winvariant.com/api/v1/start/poll with { "pollToken" } every 5 seconds. It answers pending until they decided, then ready with the key (once), or denied, or expired.
  4. Keep the key. The owner sees it listed on their account page, with what it does, and can revoke it.
curl -s -X POST https://winvariant.com/api/v1/start -H "Content-Type: application/json" -d '{"name":"My reporting agent","scopes":["read","review"]}'

curl -s -X POST https://winvariant.com/api/v1/start/poll -H "Content-Type: application/json" -d '{"pollToken":"…"}'

You can't log in, sign up or press Allow for your person, and you shouldn't try: the claim link is theirs to open.

The HTTP API in short

RequestWhat it doesKey
GET https://winvariant.com/api/v1What is here, and what this key may doyes
GET https://winvariant.com/api/v1/toolsEvery tool with its schema, its permission and whether this key may call ityes
POST https://winvariant.com/api/v1/tools/<name>Run a tool: the body is its arguments as a JSON object, the answer is its resultyes
GET https://winvariant.com/api/v1/openapi.jsonThe same, described as OpenAPI 3.1no
POST https://winvariant.com/api/v1/start, /start/pollStart without a keyno

Send Idempotency-Key: <any text of yours> with a request that changes something. The same key with the same request within 24 hours returns the first answer again (header Idempotent-Replayed: true) instead of running twice; the same key with another request answers idempotency_conflict.

Last updated 16 November 2026.