---
name: suffect
description: Get access to an API vendor (search, scraping, video, voice, inference, any paid API) with the human's one-time approval, instead of asking them to paste an API key. Use when a request fails with 401, 402, 403 insufficient scope, or documentation says an API key, account or subscription is required.
---

# Suffect

Suffect signs a human up at a vendor on your behalf after they approve the vendor's terms and a budget once. You then get a scoped, short-lived grant, usually a proxied base URL plus a token, never the vendor's long-lived key.

## When to use it

- A vendor API answers 401, 403 with an insufficient-scope message, or 402.
- A vendor's docs say "get an API key", "create an account" or "subscribe".
- The task needs a capability no connected vendor provides.

Do not ask the human to paste a key. Do not sign up at the vendor yourself. Do not solve CAPTCHAs.

## What to do

1. Call the Suffect MCP tool `request_access` with the provider's domain or slug and a budget if the task implies spend (for example `{ "provider": "exa.ai", "budget": { "amount": 20, "currency": "USD", "period": "month" } }`). Without MCP, run `suffect request exa.ai --budget 20/mo --json` with your access token in `SUFFECT_TOKEN`.
   - A catalog row whose terms carry `automated_signup_restricted` or `signup_on_behalf_restricted` (with the clause quoted under `clauses`) means the provider's terms restrict what you are about to ask for. Tell the human so in one sentence before requesting; the sheet shows the clause and their approval acknowledges it in the signed record. Suffect still proceeds, openly, as their identified agent.
2. Read the response, and keep its `request_id`:
   - `granted`: call `get_grant` with the `request_id` (or `suffect env <request_id>`) and use the returned base URL and token. Point the vendor SDK at the base URL; send the token as the bearer credential.
   - `pending_consent`: tell the human in one sentence what you asked for and give them the `consent_url`. Wait, then check with `get_grant` (or `request_access` with the `request_id`).
   - `provisioning`: approved, and the account is being created. Check again with `get_grant` in a minute.
   - `pending_takeover`: the vendor needs a human step (CAPTCHA, 2FA, an unexpected page). Give the human the `takeover_url`; check with `get_grant` after they finish. Without a `takeover_url`, read the job (`job_id`): at step `email_code` the vendor mailed a verification code to the human's own email address, which they chose on the approval; ask the human for the code, or read it from their mailbox only when they have given you access for this, and call `relay_code` with the `job_id` and the code (or `POST /v1/jobs/{job_id}/code`). Never guess a code; three at most. On the default, a Suffect alias, no code ever passes through you.
   - `denied`: stop and tell the human why. One exception: `reason` is `standing_budget_exhausted` and a `consent_url` is given, which means the standing budget this provider would use is spent for the period and the human already has a sheet to raise it; give them that link and ask again once they approve.
3. Never print the grant token or a vendor key into chat, files, logs or commit messages. Put it in the environment or pass it directly to the client.
4. If a request later fails with 401 again, the grant expired or was revoked: call `get_grant` once more. Do not retry in a loop.
5. When the task is done and you will not need the access again, call `revoke` with the `request_id`. The grant stops working at once; the human can always revoke the whole approval on their dashboard.

## What the human sees

A consent sheet with the vendor's terms (version and hash), a plain-language summary marked as not the agreement, the plan and price, the budget cap, the data shared, and one approve button that signs a consent record with their passkey. Say so when you hand them the link, in one sentence.

## Budgets

State spend in the request. The human approves a budget, and calls Suffect prices before they run are refused once it is spent (a 402 with `mandate_budget`). If the task needs more, call `set_budget` with the `mandate_id` from `list_access` and the budget you need: the human gets a new sheet for the same access with the larger budget, and nothing changes until they approve it. Tell them in one sentence why. An approval covers the agent that asked for it; another agent asks separately.