# West Kite auth.md

You are an agent. West Kite is US commercial property research and outreach, used through the MCP server at https://app.westkite.com/mcp. An account belongs to a person, so you start the connection and they finish it. It takes them about a minute. The 7-day trial needs no card.

Never ask for or handle their password. Never accept terms for them. Don't call any tool that changes something during setup.

## Which way in

- **Your client handles MCP OAuth** (Claude Code, Codex, Cursor and others): add the server and let it open the browser. See https://westkite.com/agent-quickstart.md. To open sign-up with their details filled, add `prompt=create&login_hint=<email>&first_name=<name>&last_name=<name>` to the authorization URL.
- **You can only make HTTP requests**, or run somewhere without a local callback: register below. This returns a link and a code to pass on.
- **You drive a browser for them**: open https://app.westkite.com/sign-up#login_hint=<email>&first_name=<name>&last_name=<name>. The form fills in. They choose the password, agree to the terms, and enter the emailed code unless you have their permission to read it.

## 1. Register

```http
POST https://app.westkite.com/agent/identity
Content-Type: application/json

{"type":"service_auth","login_hint":"person@example.com","first_name":"Pat","last_name":"Lee","client_name":"Your agent's name"}
```

Ask the person before sending their email. `login_hint`, the names and `client_name` are optional, but with `login_hint` only that person's account can finish. Scopes default to everything; the person chooses read only or read and write when they approve.

The response:

```json
{"registration_id":"wkc_...","registration_type":"service_auth","client_id":"wkc_...","claim_token":"clm_...","claim_token_expires":"...","post_claim_scopes":["wk:data:read"],"claim":{"user_code":"123456","expires_in":600,"verification_uri":"https://app.westkite.com/agent/claim?attempt=wka_...","interval":5}}
```

Keep `claim_token` to yourself. Older clients can send `{"type":"identity_assertion","assertion_type":"verified_email","login_hint":"..."}` for the same flow. There is no anonymous access: `anonymous` returns `anonymous_not_enabled`, and other assertion types return `issuer_not_enabled`.

## 2. Hand off

Send the person both in one message:

> Open this link, sign up or sign in, and enter this code: **123456**
> https://app.westkite.com/agent/claim?attempt=wka_...

Use the `verification_uri` exactly as returned, including anything after the `#`. The code goes in the page, not back to you.

## 3. Poll

```http
POST https://app.westkite.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_...
```

Poll every `interval` seconds. Until they finish you get `authorization_pending`; `slow_down` means wait longer, `access_denied` means they declined, and `expired_token` after 10 minutes means start again at step 1.

On success:

```json
{"access_token":"...","token_type":"Bearer","expires_in":3600,"refresh_token":"...","scope":"wk:data:read ...","client_id":"wkc_..."}
```

The standard RFC 8628 grant works too: `grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=clm_...`.

## 4. Use it

Call https://app.westkite.com/mcp over streamable HTTP with `Authorization: Bearer <access_token>`. Start with `get_profile`, then `search` with `500 Howard St San Francisco` to confirm it works.

When the token expires, refresh at https://app.westkite.com/oauth/token with `grant_type=refresh_token`, `refresh_token` and `client_id`. Refresh tokens rotate, so store the new one. The person can disconnect you at any time in Connect AI.

## Limits

Changes come back as a review link, and nothing changes until the person approves it in West Kite. Starting connections is limited to 60 a minute per address, and other OAuth requests to 300; each account gets 60 MCP requests a minute.

Discovery: https://app.westkite.com/.well-known/oauth-protected-resource/mcp, https://app.westkite.com/.well-known/oauth-authorization-server. Help: hello@westkite.com.