# TenancyVault Agent Authentication

TenancyVault exposes a read-and-draft MCP API for AI agents operating on behalf of
UK landlords and letting agents. Agents can connect via OAuth 2.0 (recommended) or
Personal Access Tokens (PATs).

## Supported identity types

- `user` — a logged-in TenancyVault account holder

## Register your agent

### Option A — OAuth 2.0 (recommended for user-facing agents)

TenancyVault supports RFC 7591 Dynamic Client Registration. No pre-registration is
required for agents that use PKCE with `token_endpoint_auth_method: none`.

POST `https://api.tenancy-vault.co.uk/v1/oauth/register`

Minimal registration body:
```json
{
  "client_name": "My Agent",
  "redirect_uris": ["https://youragent.example/callback"],
  "token_endpoint_auth_method": "none"
}
```

Full OAuth discovery: `https://api.tenancy-vault.co.uk/.well-known/oauth-authorization-server`

### Option B — Personal Access Token (PAT)

1. Sign in at https://app.tenancy-vault.co.uk/login
2. Go to **Settings → AI & Connections**
3. Create a new AI Connection → Personal Access Token
4. Select only the scopes your agent needs

## Scopes

| Scope | Description |
|-------|-------------|
| `read:portfolio` | Portfolio-level counts and attention flags |
| `read:properties` | Property list and details |
| `read:compliance` | Obligation status, deadlines, evidence gaps |
| `read:documents` | Vault document metadata (never file contents) |
| `read:acknowledgements` | Document sharing and acknowledgement status |
| `read:mtd` | Making Tax Digital readiness (requires 2FA on account) |

Draft scopes (`write:drafts`, `write:tenant_message_drafts`, etc.) are available for
agents that prepare actions for human review inside TenancyVault — they never send
messages or create official records directly.

## MCP server

- Endpoint: `https://api.tenancy-vault.co.uk/mcp`
- Transport: Streamable HTTP (stateless, RFC-compliant)
- Server Card: `https://tenancy-vault.co.uk/.well-known/mcp/server-card.json`
- Agent Skills: `https://tenancy-vault.co.uk/.well-known/agent-skills/index.json`

## Revocation

POST `https://api.tenancy-vault.co.uk/v1/oauth/revoke`
(RFC 7009 token revocation)

PATs can be revoked from Settings → AI & Connections at any time.