# Authentication

There are two credentials. Which one you use depends on the surface.

| Credential | REST API | MCP server | Who gets one |
| --- | --- | --- | --- |
| API key (`acquestor_live_…`) | Yes | Yes | Founding brokers during the beta |
| OAuth access token, from signing in through an AI host | No | Yes | Any invited member |

Both go in the `Authorization` header as a bearer token. A third credential, the acquestor.com session cookie, is used only by acquestor.com itself.

## API keys

Create keys on acquestor.com under **Account → API keys**. Creating a key asks you to sign in again.

```http
Authorization: Bearer acquestor_live_3f9a...
```

- **Prefix.** `acquestor_live_` or `acquestor_test_`, so a leaked key is easy to spot in logs and code search.
- **Shown once.** Acquestor stores a hash of the secret, never the secret.
- **Acts as you.** During the beta every key acts as the person who created it, with that person's role, and sees their own org's listings and inquiries.
- **Scopes.** Pick the fewest the job needs. A call outside the key's scopes returns 403 `insufficient_scope`.
- **Monthly credit limit.** Each key carries the most it may charge in a month, 1,000 credits unless you set another. A call that would pass it returns 402 `over_limit` and runs nothing.
- **Revoke** a key on the same page. It stops working at once.

| Scope | Grants |
| --- | --- |
| `tools:run` | Computed tools, public data and the source registry |
| `listings:read` | Listing search and detail |
| `listings:write` | Listing drafts, edits, imports and withdrawals (brokers) |
| `inquiries:read` | Your inquiries: sent, or received by your org |
| `inquiries:write` | Inquiries to listing brokers, saved as pending until confirmed |
| `deals:read` | The one deal you granted to this key, as summaries and computed results |
| `deals:write` | Save runs and add figures to the granted deal; create business records |
| `comps:read` | Comps, as the access rules allow (when the pool opens) |
| `comps:write` | Closed-deal contribution drafts (brokers), once contributions open; the account page doesn't offer it until then |

### What a key never reaches

- Another org's listings. A key sees listings only from its own org, and listing data is never sold.
- Any deal you haven't granted to it. Deals are created on acquestor.com, and a key reaches one deal only after you grant it (below).
- Anything only acquestor.com does: approving a listing, confirming an inquiry, attesting a contribution, granting deal access, deleting a deal or an account, and creating keys. These return 403 `interface_only`.

## OAuth for AI hosts

When you add the MCP server to Claude, ChatGPT or Grok, the host sends you to sign in to Acquestor. The host then holds an access token that acts as you, with your role, and with the fewest scopes your role can use: `tools:run`, `listings:read`, `inquiries:read` and `deals:read`; `inquiries:write` for a buyer; `listings:write` and `comps:write` for a broker; and `deals:write` only once you grant the host a deal. A token that carries Acquestor's own scopes gets exactly those.

- The authorization server is WorkOS AuthKit. Hosts discover it from the server's protected resource metadata (RFC 9728) at `https://mcp.acquestor.com/.well-known/oauth-protected-resource/mcp`.
- A request without a token gets 401 with a `WWW-Authenticate` header that points to that metadata; a token that isn't valid gets the same header with `error="invalid_token"`.
- Hosts register by client ID metadata document first, or by dynamic client registration.
- Tokens are bound to the MCP server (their audience is `https://mcp.acquestor.com/mcp`). The REST API doesn't accept them.
- Sign-in is invite-only during the beta. An email without an account or an open invitation is refused.

### One deal per grant

An AI host or an API key sees none of your deals until you grant it one. On acquestor.com, open the deal, turn on outside AI access, and pick the client or key from the ones that have connected as you. The client then reaches that one deal and no other; granting it a second deal replaces the first. Each access is logged on the deal, and you can revoke the grant there.

Through a grant the client gets computed results and summary figures, never raw documents. A call for any other deal returns 403 `deal_access_off`.

## Terms that apply

Using the API or connecting an AI client is covered by section 8 of the [Beta Terms](https://acquestor.com/terms) (AI clients, the API and the MCP server) and section 4.4 of the [Privacy Notice](https://acquestor.com/privacy) (what an AI client you connect receives). What a host receives is held by that host's provider under your account there, under its own terms.

## Pending writes

Writes that reach another person wait for you on acquestor.com. An inquiry created with an API key or by an AI client is saved as `pending_confirmation`; it goes to the listing broker only when you confirm it on acquestor.com. A listing drafted through the API stays a draft until the broker approves it there.