# India Property Register auth.md

You are an AI agent. India Property Register (https://indiapropertyregister.com) is the land and property register of India: every state, district,
tehsil and village with LGD codes, boundaries and pincodes, each state's land-record portals, and plots as they load. Use it through the REST API
(`https://indiapropertyregister.com/api/v1`, OpenAPI: `https://indiapropertyregister.com/api/v1/openapi.json`) or the MCP server (`https://indiapropertyregister.com/mcp`, Streamable HTTP).
Every call needs a credential of a person's India Property Register account, sent as `Authorization: Bearer <token>`.

Billing: each account has a prepaid wallet. New accounts get ₹50 of free credit. Each successful call
(HTTP 200) costs ₹0.16; errors are free. Top-ups: ₹500, ₹5,000 or ₹50,000 of credit, plus 18% GST.

Discovery: protected resource metadata `https://indiapropertyregister.com/.well-known/oauth-protected-resource` (and `/mcp` suffixed),
authorization server metadata `https://indiapropertyregister.com/.well-known/oauth-authorization-server` (its `agent_auth` block
describes method 2 below). Scope: `api`.

## 1. OAuth 2.1 (when the person can use a browser)

Authorization code + PKCE (S256). Register with `POST https://indiapropertyregister.com/oauth/register` (RFC 7591, public client,
`token_endpoint_auth_method: none`) or use a Client ID Metadata Document URL as `client_id`. Send the person
to `https://indiapropertyregister.com/oauth/authorize`; they sign in with a code emailed to them, or create an account there (with the
free credit), and allow your client. Exchange the code at `https://indiapropertyregister.com/oauth/token`. Access tokens last 30 days;
refresh with `grant_type=refresh_token` (refresh tokens last 180 days and rotate). Revoke at
`https://indiapropertyregister.com/oauth/revoke`. MCP clients (Claude, ChatGPT, Cursor and others) do all of this when given `https://indiapropertyregister.com/mcp`.

## 2. Agent sign-up by email (verified email, no browser)

Ask the person first: tell them you will create or connect their India Property Register account, and get their email.

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

{"login_hint": "person@example.com", "name": "Asha Verma", "company": "Verma Traders", "agent_name": "My Assistant"}
```

`name`, `company` and `agent_name` are optional (they fill in a new account and name you in the mail).
`{"type": "identity_assertion", "assertion_type": "verified_email", "assertion": "<email>"}` is accepted too.
We email the person a 6-digit code (valid 10 minutes) and answer `202` with `status: "code_sent"`.

Ask the person for the code, then:

```http
POST https://indiapropertyregister.com/agent/identity/claim
Content-Type: application/json

{"login_hint": "person@example.com", "code": "123456"}
```

Response `201`: `{"api_key": "ick_...", "token_type": "Bearer", "new_account": true, "account": {"balance_inr": 50, ...}}`.
A new account is created when none exists, with ₹50 of free credit. Errors: `invalid_code` (ask again),
`expired_token` or `too_many_attempts` (start again at /agent/identity), `rate_limited`.
Keep the key secret and use it only for this person. They can see and revoke it at https://indiapropertyregister.com/account/keys.

## 3. Use, check the wallet, and top up

- Data: `GET https://indiapropertyregister.com/api/v1/search?q=Rampur`, `/api/v1/village/{LGD code}`, `/api/v1/tehsil/{LGD}/villages`,
  `/api/v1/sources?state={LGD}` ... (OpenAPI lists all). MCP: `https://indiapropertyregister.com/mcp`.
- Wallet (free): `GET https://indiapropertyregister.com/api/v1/account` gives the balance and calls remaining.
- `402 insufficient_balance` means the wallet is empty. With the person's OK, `POST https://indiapropertyregister.com/api/v1/account/topup`
  with `{"amount": 500}` (or 5000, 50000; 18% GST is added to the amount paid). The answer has a `pay_url`: give it to the person, who
  pays by UPI, card, net banking or wallet. Poll `status_url` until `"status": "paid"`; the credit is then
  in the wallet. The same top-up is offered as UCP (`https://indiapropertyregister.com/.well-known/ucp`) and ACP (`https://indiapropertyregister.com/.well-known/acp.json`)
  checkout sessions with hosted payment (`requires_escalation` + `continue_url`). You never handle card or UPI details.
- Usage log (free): `GET https://indiapropertyregister.com/api/v1/account/usage`; the person can download every call as CSV from https://indiapropertyregister.com/account/usage.

Rules: act only on what the person asked; do not top up without their OK; do not bulk-scrape or resell data.
Revenue records are not proof of title and nothing here is a certified copy: say so when you report ownership.
Terms: https://indiapropertyregister.com/terms. Privacy: https://indiapropertyregister.com/privacy. Refunds: https://indiapropertyregister.com/refunds. Help: support@indiapropertyregister.com.