# Ownify Agent API Authentication

> Machine-readable agent registration and authentication instructions for the
> Ownify Agent API. This file follows the **auth.md** convention
> (https://workos.com/auth.md) so AI agents can discover how to obtain access
> to Ownify's protected endpoints.

## Overview

Ownify exposes a small, server-to-server **Agent API** that lets approved
partners (mortgage brokers, agent tools, AI assistants) create a preliminary
homeownership plan on behalf of a homebuyer. Endpoints are bearer-token
authenticated and rate-limited per partner.

- **Resource identifier:** `https://ownify.com/api`
- **Token type:** Bearer (opaque, long-lived API key)
- **Transport:** HTTPS only
- **Token placement:** `Authorization: Bearer <token>` request header
- **Protected resource metadata:** [/.well-known/oauth-protected-resource](https://ownify.com/.well-known/oauth-protected-resource)

## Registering an agent

Token issuance is currently **manual** (no self-service OAuth Dynamic Client
Registration yet). To request credentials:

1. Email **agents@ownifyhome.com** from the operator account that will own
   the integration. Include:
   - Organization / product name
   - Public website or app URL
   - A short description of the agent's purpose
   - Whether the agent acts on behalf of consumers, internal staff, or both
   - Expected request volume (requests/day)
2. Ownify reviews the request and, on approval, issues a single bearer
   token via a one-time secure link (1Password / Bitwarden Send).
3. Store the token as a server-side secret. It must never be shipped to a
   browser or mobile client. Revocation is immediate on request.

There is no consumer login or consent step — the token represents the
**partner**, not an end user. Submitted homebuyer information must have been
collected by the partner with the homebuyer's explicit consent.

## Endpoints

### `POST https://qgilyxdvapqroijtjrom.functions.supabase.co/generate-myplan`

Create a preliminary Ownify homeownership plan for a homebuyer and trigger
the standard plan-delivery email. Returns immediately (`202 Accepted`) and
processes the plan asynchronously.

**Headers**

| Header          | Value                                  |
| --------------- | -------------------------------------- |
| Authorization   | `Bearer <token>`                       |
| Content-Type    | `application/json`                     |

**Request body** (JSON)

| Field             | Type            | Required | Notes                                          |
| ----------------- | --------------- | -------- | ---------------------------------------------- |
| email             | string          | yes      | Homebuyer email                                |
| firstName         | string          | no       | Defaults to "Friend"                           |
| lastName          | string          | no       |                                                |
| cityOrZip         | string          | no       | Target city or ZIP                             |
| zip               | string          | no       | Optional ZIP if separate from cityOrZip        |
| annualIncome      | number / string | no       | Gross household income, USD                    |
| monthlyDebt       | number / string | no       | Recurring monthly debt obligations, USD        |
| creditScore       | string          | no       | e.g. "720-739", "Unknown"                      |
| downPayment       | number / string | no       | Cash available for down payment, USD           |
| military          | string          | no       | "Yes" / "No"                                   |
| firstTimeBuyer    | string          | no       | "Yes" / "No" (defaults to "Yes")               |
| propertyType      | string          | no       | "Single family", "Condo", etc.                 |
| timeline          | string          | no       | "0-3 months", "Just exploring", etc.           |
| hubspotContactId  | string          | no       | If the partner already has a HubSpot contact   |

**Responses**

- `202 Accepted` — `{ "ok": true, "status": "accepted" }`
- `400 Bad Request` — invalid JSON or invalid email
- `401 Unauthorized` — missing or invalid bearer token
- `405 Method Not Allowed` — non-POST request
- `500 Internal Server Error` — server misconfiguration

### Example

```bash
curl -X POST \
  https://qgilyxdvapqroijtjrom.functions.supabase.co/generate-myplan \
  -H "Authorization: Bearer $OWNIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "firstName": "Alex",
    "lastName": "Rivera",
    "cityOrZip": "Raleigh, NC",
    "annualIncome": 95000,
    "monthlyDebt": 600,
    "creditScore": "720-739",
    "downPayment": 8000,
    "firstTimeBuyer": "Yes",
    "timeline": "0-3 months"
  }'
```

## Scopes

Currently a single implicit scope is granted per token:

- `plans:create` — submit homebuyer information to generate a preliminary plan.

Additional scopes (e.g. `plans:read`, `markets:read`) will be added as more
endpoints come online; partners do not need to re-register when new scopes
ship.

## Rate limits

Default: **60 requests / hour / token**. Bursts up to 10 RPS are tolerated.
Contact agents@ownifyhome.com for higher limits.

## Revocation and rotation

Email **agents@ownifyhome.com** to revoke or rotate a token. Revocation
takes effect within 60 seconds. There is no public revocation endpoint at
this time.

## Contact

- General: hello@ownifyhome.com
- Agent / API: agents@ownifyhome.com
- Security: security@ownifyhome.com