Get started

Authentication

Every request carries an API key that belongs to your organization. Scopes on the key decide which endpoints and tools it can reach, and your plan decides which scopes exist.

API keys

Send the key as a bearer token on every request, to both the REST API and MCP:

Header

Authorization: Bearer gfk_4mQx…

Created by an organization admin in the app under Org admin → Integrations → Create API key. Each key has a name (up to 120 characters) and a set of scopes.
Shown once. Keys look like gfk_ followed by 43 random characters. Greenfinch stores only a SHA-256 hash of the secret, so it cannot show the key again; copy it when it is created.
Revocable. An admin can revoke a key at any time; the next request with it gets 401. To rotate, create the new key, deploy it, then revoke the old one.
Limited in number. An organization can hold up to 10 active keys. Creating an eleventh is refused with CREDENTIAL_LIMIT_REACHED until one is revoked.
Organization-level. A key acts for the organization as a whole, not for a person. It sees the whole service area of the organization, and actions it takes are recorded as made through that key. A few tools need a person behind them (writing a note, saving a search) and refuse keys — use a per-user connection for those.

curl "https://app.greenfinch.ai/api/v1/me" \
  -H "Authorization: Bearer $GREENFINCH_API_KEY"

GET /me answers for any live key regardless of scope, which makes it the right health check for a stored key.

Scopes

A key can only call what its scopes allow. Opt-in scopes are never pre-selected when a key is created; the admin has to tick them deliberately. A call without the scope is refused with 403 and SCOPE_NOT_GRANTED.

Scope	Allows	Plan	Access	Opt-in
`events:subscribe`	Subscribe and unsubscribe webhooks (`POST /webhooks`, `DELETE /webhooks/{id}`) and poll the qualified-lead feed (`GET /leads`).	Team	Write	No
`leads:read_single`	Read one lead bundle at a time (`GET /leads/{id}`). Metered like an export.	Team	Read	No
`pipeline:write`	Report won or lost from your CRM (`POST /leads/{id}/status`).	Team	Write	No
`accounts:sync`	Mark properties as active or churned customers (`POST /customer-accounts/sync`).	Team	Write	No
`account:read`	Credit balance, export allowance and licensed coverage (`GET /account`).	Team	Read	Yes
`events:read`	The organization's outbound lead-event history (`GET /events`).	Team	Read	Yes
`notes:read`	Notes your team left on a property (`GET /notes`).	Team	Read	Yes
`lists:read`	Saved lists and their item counts (`GET /lists`).	Team	Read	Yes
`lists:write`	Create lists and add items (`POST /lists`, `POST /lists/{id}/items`).	Team	Write	Yes
`property:read`	One property's record and research state (`GET /properties/{id}`). Never returns contact details.	Team	Read	Yes
`data:read`	Search and read properties, contacts and organizations (`POST /properties/search`, `GET /properties/{id}/detail`, the `/contacts` and `/organizations` endpoints). Viewing a contact your subscription covers but you have not revealed counts toward the daily contact limit.	Enterprise	Read	Yes
`data:unlock`	Unlock a property (`POST /properties/{id}/unlock`, 10 credits) or reveal a contact (`POST /contacts/{id}/reveal`, 5 credits). Anything already unlocked is not charged again.	Enterprise	Write	Yes
`mcp`	The MCP endpoint and all its tools — search, reveals, research, lists, pipeline and account — subject to your agent settings and daily limits.	Enterprise	Read and write	Yes
`pipeline:transitions_full`	Lets `greenfinch_update_lead_status` move leads to attempted contact, active opportunity, won or lost. Not chosen at creation: an admin turns it on for an existing key on the Integrations page.	Enterprise (with mcp)	Write	Yes

Scopes are checked against your live plan

Every request checks two things: that the key was granted the scope, and that your organization's plan today still includes it. Plans are never baked into keys. If your organization moves from Enterprise to Team, a key holding mcp starts receiving 403 on the next request:

403 · plan does not include the scope

{
  "success": false,
  "error": "API Access isn't included on your current plan. Contact sales for API access.",
  "code": "UPGRADE_REQUIRED",
  "feature": "apiAccess",
  "minimumTier": "enterprise"
}

The same live check covers account state: a suspended organization gets 403 ORG_SUSPENDED, and a closed account gets 403 ACCOUNT_CLOSED, whatever the key allows.

What your plan includes

Two plans reach the API. Team opens the integration surface — the channels that move leads between Greenfinch and the systems your team already runs. Enterprise adds the data surface: search, read and unlock over REST, and the full tool surface for AI assistants.

	Team	Enterprise
Integrations	Webhooks, Zapier and CRM deliveries, single lead bundles, pipeline write-back, customer-account sync, and read access to events, notes, lists and property records	Everything in Team
Data over REST	No	Search, read, unlock and reveal properties, contacts and organizations (the data scopes)
MCP connector	No	The full tool surface for AI assistants and agents — search, research, lists, pipeline and account tools — as an organization key or a per-user connection
Request rate	120 requests a minute, per key	300 requests a minute, per key
Per-prospect deliveries	A free monthly allowance, then one credit per delivered bundle (Lead bundles)	Draw the records allowance, at no credit cost, rather than being metered per delivery
How much data may leave	Bounded by the daily limits your admins set	A records allowance sized to your order: how many distinct records may be taken per billing period, across every door, with the daily limits derived from it

API and connector access is bounded by limits that scale with the size of your Enterprise plan; your order states the numbers. A larger licensed territory carries a larger records allowance, and the daily limits follow it rather than being chosen separately. Nothing is metered in the dark: every limit in force, and today's use against it, is readable from the app and from the API.

Availability

The plan features above are live today, the records allowance included. The allowance applies to your organization once Greenfinch records the allowance your Enterprise order states; until then, Enterprise per-prospect deliveries stay on the per-delivery meter described under Lead bundles. Team plans are not affected by it.

Connect an AI assistant

Besides organization keys, the MCP endpoint supports a per-user connection for AI assistants that implement MCP authorization (OAuth). Where it is available, a member adds Greenfinch as a connector in their assistant, signs in with their own Greenfinch account, and approves the connection — no key is copied anywhere.

It acts as that member. The assistant sees what the member sees in the app: their assigned territory, the lists they can open, and the same role rules. An assistant connected by a read-only member cannot run tools that write or spend.
It needs an active seat. A member without a seat cannot use Greenfinch through an assistant either (NO_ACTIVE_SEAT).
Admins stay in control. An organization can limit connections to its admins (other members are refused with MEMBER_CONNECT_DISABLED). A connection that has been revoked stays revoked — signing in again does not restore it — and is refused with GRANT_REVOKED.
Discovery. An unauthenticated request to the MCP endpoint is answered 401; when sign-in is enabled for your environment, the response carries a WWW-Authenticate header pointing assistants at the protected-resource metadata, which is how they start the sign-in flow.

Availability

Per-user sign-in depends on the assistant supporting MCP authorization and on it being enabled for your organization. If your assistant cannot sign in, use an organization key with the mcp scope instead; everything except the few per-user tools works the same. Ask your Greenfinch contact if you are unsure which applies to you.

Keeping keys safe

Give each system its own key, with only the scopes it needs.
Store keys in a secrets manager, never in client-side code or a repository.
Set daily limits per key on the Integrations page so a misbehaving job cannot reveal or export more than you expect — see Limits.
Revoke keys you no longer use. The Integrations page shows when each key was last used.

PreviousFor coding agents Next REST API