---
type: auth-md
version: "1.0"
issuer: "https://smartnagari.com"
authorization_servers:
  - "https://smartnagari.com"
registration_uri: "https://smartnagari.com/auth.md"
supported_identity_types:
  - "anonymous"
  - "identity_assertion"
supported_credential_types:
  - "bearer_token"
scopes_supported:
  - "read:properties"
  - "read:services"
  - "read:advisory"
  - "submit:inquiry"
contact: "invest@smartnagari.com"
---

# auth.md

You are an autonomous AI agent. This document describes how agents discover, register, authenticate, and call APIs on Smart Nagari real estate advisory services.

## Step 1 — Discovery

Smart Nagari advertises machine-readable discovery documents at standard well-known locations:

- **OAuth Protected Resource (PRM):** `/.well-known/oauth-protected-resource`
- **OAuth Authorization Server:** `/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery:** `/.well-known/openid-configuration`
- **JSON Web Key Set (JWKS):** `/oauth/jwks` or `/.well-known/jwks.json`
- **Agentic Resource Discovery (ARD):** `/.well-known/ai-catalog.json`
- **MCP Server Card:** `/.well-known/mcp/server-card.json`
- **A2A Agent Card:** `/.well-known/agent-card.json`

## Step 2 — Registration & Identity Methods

Smart Nagari supports two primary agent registration pathways:

### Method A: Anonymous Access (Default / Public Read)
For public property discovery, land plot inspection, and investment guides, agents require no pre-issued credentials.
1. Send requests directly with header `Accept: text/markdown` or `Accept: application/json`.
2. To obtain an ephemeral bearer session for rate-limit separation, POST to `/oauth/token` with `grant_type=client_credentials` and client ID `anonymous`.

### Method B: Identity Assertion (ID-JAG / Verified Email)
When acting on behalf of an authenticated principal or investor:
1. Mint an identity assertion (JWT) signed by your trusted provider with:
   - `aud`: `https://smartnagari.com`
   - `iss`: your provider issuer URL
   - `sub`: agent principal identifier
2. Exchange the assertion at `/oauth/token` using grant type `urn:ietf:params:oauth:grant-type:jwt-bearer`.

## Step 3 — Token Exchange

```http
POST /oauth/token HTTP/1.1
Host: smartnagari.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=read:properties%20read:services%20read:advisory
```

Response:
```json
{
  "access_token": "anonymous_public_access_token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read:properties read:services read:advisory submit:inquiry"
}
```

## Step 4 — Supported Scopes

- `read:properties` — Discover curated property listings, plots, residential, and commercial developments in Ahmedabad and Dholera SIR.
- `read:services` — Access investment advisory service models, TP scheme analyses, and land banking frameworks.
- `read:advisory` — Access market intelligence, infrastructure milestones, and capital compounding research.
- `submit:inquiry` — Submit investment consultation requests and buyer inquiries via `/api/contact`.

## Step 5 — Calling Protected Endpoints

Send the bearer token in the HTTP `Authorization` header:

```http
GET /api/properties HTTP/1.1
Host: smartnagari.com
Authorization: Bearer <access_token>
Accept: application/json
```

## Step 6 — Revocation

To revoke an active token or session:

```http
POST /oauth/revoke HTTP/1.1
Host: smartnagari.com
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

## Rate Limits & Best Practices

- **Standard public requests:** 60 requests/minute per client IP.
- **Backoff behavior:** Always honor HTTP 429 status codes and the `Retry-After` header.
- **Content Negotiation:** Pass `Accept: text/markdown` on any page URL to retrieve clean, token-optimized Markdown with HTML tags and SVGs pre-stripped.