> ## Documentation Index
> Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent signup

> Request a Finta account by email, verify in the browser, and connect your AI app

> [!WARNING]
>
> Coming soon: agent signup is behind a rollout flag that is off by default.
> While paused, `POST /api/v1/signups` returns `503 signups_paused` and the MCP
> stays sign-in-only. Use [web signup](https://app.finta.com/signup) instead.
> The flow below describes signup once rollout is enabled.

An agent can request a Finta account with only the user's email. The person
verifies that email in their own browser, then connects Finta to the AI app and
clicks **Allow**. No password, company, API key, or OAuth grant is needed to
request signup. Finta's MCP uses OAuth after activation; never create an API key
for an MCP connection.

## Confirm the email

Before signup, use context the user has allowed you to access, such as the
conversation, local files, `git config user.email`, or connected tools. Propose
the email with its source and confirm it with the user; never guess. If no email
is available, ask for it. Someone who already uses Finta should connect and sign
in instead of requesting signup.

You can gather company context at the same time: incorporation year, entity type,
state, what the company sells, foreign subsidiaries now or planned, banks, and
credit cards. Present prefilled answers with their sources, conflicts and missing
questions together for confirmation. These answers are not signup request fields.
The agent-facing entry point at [app.finta.com/llms.txt](https://app.finta.com/llms.txt)
also explains the flow.

## Request signup

Call [Create signup](https://www.finta.com/docs/api-reference/onboarding/create-signup.md) without a bearer
credential:

```bash theme={null}
curl -X POST https://app.finta.com/api/v1/signups \
  -H "Content-Type: application/json" \
  -d '{"email":"founder@acme.com"}'
```

Only `email` is required. Finta trims surrounding whitespace and lowercases it.
REST also accepts optional `app` for verification email/page branding, such as
`codex` or `claude-code`. When omitted, Finta detects the app from User-Agent.
Unknown values use generic agent branding and do not cause an error; branding
does not change signup behavior or quotas. The reference schema lists the
supported app keys.

A successful request returns HTTP **202 Accepted**:

```http theme={null}
HTTP/1.1 202 Accepted
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1792785660

{
  "status": "verification_sent",
  "email": "founder@acme.com",
  "expires_in_seconds": 3600,
  "mcp_url": "https://mcp.finta.com/mcp",
  "next_step": {
    "action": "open_verification_link",
    "message": "Tell the user: \"Click Activate in the email Finta just sent you at founder@acme.com.\" They click it in their own browser; never fetch the link. Then connect Finta's MCP (https://mcp.finta.com/mcp) the way your app supports; they sign in with one Allow. If your app must restart to load it, tell them exactly how to restart and come back to this chat, and call no Finta tool until then. E.g. Codex CLI: they quit (Ctrl+C twice) and run `codex mcp add finta --url https://mcp.finta.com/mcp && codex resume --last` (don't run it yourself); Claude Code: run `claude mcp add --transport http finta https://mcp.finta.com/mcp` if you haven't, then they run /mcp and pick finta. Once connected, call get_onboarding and follow next_step.message. No email? Existing accounts get none; just connect and sign in."
  }
}
```

Read these fields as instructions:

| Field | Meaning |
| - | - |
| `status` | Always `verification_sent`: follow the verification instructions. This does not confirm account creation or email delivery. |
| `email` | The supplied email, trimmed and lowercased. |
| `expires_in_seconds` | Always `3600`: the lifetime of a verification link when one is issued. Present even when no email is sent. |
| `mcp_url` | The environment's OAuth MCP URL. Use this value rather than hardcoding production. |
| `next_step.action` | Always `open_verification_link`: the human verification step. |
| `next_step.message` | Instructions for activation, connecting the app, and returning to the conversation after any required restart. Follow this message. |

New, pending, active, inactive and deleted accounts receive the same 202 body and
consume the same email allowance. New accounts receive a verification email.
Pending accounts receive a replacement one-hour link that invalidates the prior
link. Existing active, inactive and deleted accounts receive **no email**.
Neither a 202 nor a 429 reveals whether an account exists.

Only a newly created account schedules Finta's standard welcome and follow-up
emails, starting at signup before activation: a welcome after 10 minutes and a
check-in after two days, subject to the usual delivery eligibility checks.
Pending-account resends, existing accounts and team invitations do not schedule
these emails again. The public 202 response is unchanged.

If no account exists and the email has a pending team invitation, Finta resends
that invitation instead of creating an owner account, matching web signup. The
202 response and signup allowance are identical; sending the invitation does
not consume a second email allowance. An unexpired invitation keeps its token
and expiry; an expired invitation receives a fresh link valid for 30 days, and
the old link remains invalid. Follow the invitation to join the existing company.

Every admitted request queues the same background job. Failures creating the
account, renewing a link, enqueueing the job, or sending mail after admission
are reported internally and keep the same public success response. The email
allowance remains consumed. Success confirms neither creation nor delivery.
There is no account-status or verify endpoint to poll.

## Activate and connect

1. Tell the user to click **Activate** in Finta's email in their own browser.
   The agent must never fetch the verification link. Opening the page alone does
   not activate the account; the person must click Activate. Links expire after
   one hour.
2. Activation signs that browser in. Return to the identified AI app and connect
   Finta using the response's `mcp_url`; the browser can return to the app's
   **Allow** screen. Existing MFA factors still require normal sign-in.
3. Follow `next_step.message` for connecting and any required restart. Tell the
   person exactly how to restart and return to this conversation, and call no
   Finta tool until the app has loaded the connection. See
   [MCP connection instructions](https://www.finta.com/docs/mcp/introduction.md#connect).
4. Once connected, follow the returned guidance to call `get_onboarding` and
   continue with `next_step.message`.

Agent-created accounts have a random password. Activating an agent-issued link
also replaces any password on a pending account, including one chosen during a
prior web signup. Requesting signup or opening the activation page does not
change that password. Ordinary web activation links keep their chosen password.
The user can use **Forgot password** later to set a password for email/password
login.

If no email arrives after a few minutes, existing users can connect and sign in
without it, using Forgot password if appropriate. Retrying signup consumes
another allowance and may invalidate an earlier pending link; avoid automatic,
indefinite retries.

## Signed-out MCP signup

When rollout is enabled, supported non-CLI clients can initialize, discover
tools and call `sign_up` while signed out. `sign_up` accepts only `email` and
returns the normalized email, `verification_sent` status, one-hour lifetime and
`next_step` instructions. Branding comes from User-Agent. The signup tool declares
`noauth`; protected tools declare OAuth scopes. Once connected, signup is hidden
and calls to it are refused, including during onboarding.

Coding clients with a `claude-code` or `codex` User-Agent prefix receive HTTP
**401** with `WWW-Authenticate` and use REST signup instead. For other signed-out
clients, protected calls trigger OAuth with HTTP 401 and `WWW-Authenticate`.
An `openai-mcp` client instead receives HTTP 200 with a JSON-RPC tool error,
`isError: true`, the message “Sign in to Finta to continue.” and the Bearer
challenge in `_meta["mcp/www_authenticate"]`.

Invalid or expired bearer tokens, tokens for a different resource and API keys
remain refused. Signed-out discovery does not grant access to company data.
Manual claude.ai and ChatGPT verification is still outstanding; this describes
the server contract rather than verified client behavior.

## Limits and errors

REST signup always uses **120 requests/minute per IP**, even if a credential is
sent. Enabled anonymous MCP traffic uses a separate **6,000 requests/minute per
IP** bucket; that initial provider-proxy budget is pending confirmation. Neither
request budget raises the email allowances shared with web signup:

* 3 attempts per recipient per 30 minutes and 5 per 24 hours.
* 10 auth emails per caller IP per 10 minutes and 100 per 24 hours; IP allowances
  are shared across auth email purposes, including provider egress IPs.

All account states consume the same allowances. Changing User-Agent does not
bypass them. Signup uses no company permissions, onboarding gate, monthly API/MCP
allowance, or API request logging.

| Status and code | What to do |
| - | - |
| `400 parameter_missing` | Supply a nonblank `email`. |
| `422 invalid_email` | Correct the email; `param` is `email`. |
| `429 rate_limit_exceeded` | Wait at least `Retry-After` seconds, whether limited by requests or email allowance. |
| `503 signups_paused` | Use [web signup](https://app.finta.com/signup); repeated requests do not enable rollout. |

MCP signup errors are tool results with `isError: true`, the REST error code in
text and structured content, and retry seconds for throttling. See
[Errors](https://www.finta.com/docs/api-reference/errors.md#invalid_email) for full HTTP examples and
[Signup email allowances](https://www.finta.com/docs/api-reference/usage-limits.md#signup-email-allowances)
for headers and retry guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.