# auth.md

You are an agent. This document tells you how to register with Home Invest, how public credentials work, and how a human can claim or revoke that registration.

Home Invest publishes public discovery APIs and MCP tools. Read-only resources do not require a credential. Registration issues a correspondence api_key so you can claim or revoke the registration later. That key does not unlock investor-only data.

Both roles live on one host. The resource server is https://homeinvest.com and the authorization server is https://homeinvest.com.

## Audience

Agents that need structured facts about Home Invest, multifamily investing, Opportunity Zones, the Academy, or how a human can book a call with the team.

## Discovery

Read these two documents in this order. The protected resource metadata names an authorization server, the agent:read scope, and bearer tokens in the Authorization header.

- Fetch https://homeinvest.com/.well-known/oauth-protected-resource and read resource, resource_name, authorization_servers, scopes_supported, bearer_methods_supported, and the agent_auth block.
- Fetch https://homeinvest.com/.well-known/oauth-authorization-server and read the agent_auth block: skill, register_uri, claim_uri, revocation_uri, identity_types_supported, and anonymous.credential_types_supported.

skill must be https://homeinvest.com/auth.md. Follow register_uri, claim_uri, and revocation_uri from that block.

There is no 401 challenge on public read tools. Use the well-known documents; do not probe protected investor systems.

Protected Resource Metadata: https://homeinvest.com/.well-known/oauth-protected-resource
Authorization Server Metadata: https://homeinvest.com/.well-known/oauth-authorization-server
Auth.md: https://homeinvest.com/auth.md

## Public access

Use any of these without Authorization:

- GET https://homeinvest.com/api/agent
- POST https://homeinvest.com/mcp (MCP Streamable HTTP)
- GET https://homeinvest.com/openapi.json
- Homepage markdown via Accept: text/markdown

Supported scope: agent:read. Bearer tokens, when present, go in the Authorization header.

## Human / accredited-investor access

There is no self-serve OAuth token that unlocks investor-only offerings. Current public offerings live at https://homeinvest.cashflowportal.com/offerings/public. For a conversation with the team:

1. Book a call: https://homeinvest.com/book
2. Email: support@homeinvest.com

## Supported identity types

- anonymous — POST JSON to the register URI. Home Invest returns a correspondence api_key.
- identity_assertion / verified_email — include a contact email at registration, then complete the claim ceremony so a human can own the registration.

## Registration

POST https://homeinvest.com/api/agent/register

```json
{
  "type": "anonymous",
  "requested_credential_type": "api_key",
  "name": "your-agent-name",
  "email": "operator@example.com",
  "purpose": "read public Home Invest facts"
}
```

Response includes registration_id, credential_type: "api_key", and credential. Store the credential if you will claim or revoke later. Public GET/POST discovery endpoints work the same with or without it.

## Claim

POST https://homeinvest.com/api/agent/claim

Send registration_id and email. Home Invest does not run a device-code loop. The response returns https://homeinvest.com/book and support@homeinvest.com so a human can confirm ownership.

## Revocation

POST https://homeinvest.com/api/agent/revoke

Send registration_id (and credential if you have it). Home Invest acknowledges the request and points the operator to support@homeinvest.com to finish deletion of stored correspondence.

## agent_auth

```json
{
  "agent_auth": {
    "skill": "https://homeinvest.com/auth.md",
    "documentation_uri": "https://homeinvest.com/auth.md",
    "register_uri": "https://homeinvest.com/api/agent/register",
    "identity_endpoint": "https://homeinvest.com/api/agent/register",
    "claim_uri": "https://homeinvest.com/api/agent/claim",
    "claim_endpoint": "https://homeinvest.com/api/agent/claim",
    "revocation_uri": "https://homeinvest.com/api/agent/revoke",
    "contact": "support@homeinvest.com",
    "identity_types_supported": [
      "anonymous",
      "identity_assertion"
    ],
    "supported_identity_types": [
      "anonymous",
      "identity_assertion"
    ],
    "anonymous": {
      "credential_types_supported": [
        "api_key"
      ],
      "claim_uri": "https://homeinvest.com/api/agent/claim"
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "verified_email"
      ],
      "credential_types_supported": [
        "api_key"
      ],
      "claim_uri": "https://homeinvest.com/api/agent/claim"
    },
    "credential_types_supported": [
      "api_key"
    ],
    "credentials_note": "The api_key identifies a registration for claim or revocation. Public Home Invest discovery APIs and MCP tools do not require it."
  }
}
```