Visa Key API

Visa Keys let an approved account run paid Visa tools from a backend, scheduled job, or headless agent without opening an MCP approval prompt for every call. A key spends from the owner's prepaid balance, and server-side caps, allowlists, environment scoping, and idempotency protect the money path.

Use the CLI for the common key lifecycle, then send the key to the HTTP API:

copyvisa-cli keys create my-demo-app --tools fal-flux-pro,or-gpt-4o-mini --daily-cap 5 --total-cap 200
visa-cli keys list
visa-cli keys revoke 1

The raw VisaKey_... secret is printed once when the key is created. Store it in your app secret manager. Do not commit it, paste it into chat, or expose it to browsers.

Base URLs

Visa Keys are environment-scoped. A preview key used against production, or a production key used against preview, returns 401 KEY_ENVIRONMENT_MISMATCH.

Create A Key

CLI:

copyvisa-cli keys create my-demo-app --tools or-gpt-4o-mini --daily-cap 5 --total-cap 200

HTTP:

copycurl -sS https://auth.visacli.sh/v1/api/keys \
  -H "Authorization: Bearer $VISA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-demo-app",
    "allowed_tools": ["or-gpt-4o-mini"],
    "daily_cap_cents": 500,
    "total_cap_cents": 20000,
    "tool_scope": "restricted"
  }'

Important fields:

Create returns the raw key once:

copy{
  "success": true,
  "key": "VisaKey_...",
  "key_prefix": "VisaKey_abc123...",
  "id": 123,
  "label": "my-demo-app",
  "owner": "octocat",
  "allowed_tools": ["or-gpt-4o-mini"],
  "tool_scope": "restricted",
  "daily_cap_cents": 500,
  "total_cap_cents": 20000,
  "environment": "production"
}

Execute A Tool

Every direct paid execution requires both X-Api-Key and an Idempotency-Key.

Route:

copyPOST /v1/api/tools/:tool/execute

copyidem=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -sS https://auth.visacli.sh/v1/api/tools/or-gpt-4o-mini/execute \
  -H "X-Api-Key: $VISA_KEY" \
  -H "Idempotency-Key: $idem" \
  -H "Content-Type: application/json" \
  -d '{"input":{"messages":[{"role":"user","content":"Say hello in one sentence."}]}}'

Request shape:

Do not send max_cents, dry_run, stream: true, session budget ids, voucher fields, or raw top-level tool parameters. Put provider parameters under input.

Success responses use a stable tool-execution envelope:

copy{
  "success": true,
  "object": "tool_execution",
  "tool": "or-gpt-4o-mini",
  "result": {},
  "usage": {
    "charged_cents": 1,
    "charged_micros": "10000"
  },
  "receipt": null
}

List And Revoke Keys

CLI:

copyvisa-cli keys list
visa-cli keys revoke 123

HTTP list:

copycurl -sS "https://auth.visacli.sh/v1/api/keys?limit=25" \
  -H "Authorization: Bearer $VISA_SESSION_TOKEN"

List responses include cursor metadata:

copy{
  "success": true,
  "keys": [],
  "limit": 25,
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null
}

Use starting_after to move to older keys with next_cursor, or ending_before to move back toward newer keys with previous_cursor. Do not send both cursors in the same request.

HTTP revoke:

copycurl -sS -X DELETE https://auth.visacli.sh/v1/api/keys/123 \
  -H "Authorization: Bearer $VISA_SESSION_TOKEN"

Revoked keys can no longer execute tools. Revoke returns:

copy{ "success": true, "revoked": 123 }

Update And Rotate

The HTTP API also supports key updates and rotation for control-plane clients:

Rotation returns the replacement raw key once. Store it immediately, deploy it to the consuming service, then remove the old secret from that service.

Errors And Retries

Errors use a structured JSON envelope:

copy{
  "success": false,
  "error": "human-readable message",
  "error_code": "INVALID_REQUEST",
  "retryable": false,
  "retry_after": 5
}

Branch on retryable, error_code, and Retry-After; do not parse message text.

For retryable errors, wait for retry_after or Retry-After, then resend the identical request with the same Idempotency-Key. For non-retryable errors, change the request or reconcile using the returned support and receipt fields before trying again.