# Account

> In active development. This is the specification.

## GET /me

The first call any integration should make, and the one to repeat after any authorization change. It answers whose account you are holding, what you may do with it, and — for a blog integration — which site the host picked. Your rate-limit budget is on the `X-RateLimit-*` headers of every response, this one included.

Requires `account:read`, which is on every grant automatically. It is the one scope you cannot decline, because an application that cannot tell which account it is acting for cannot behave correctly.

```bash
curl https://www.bookwithhaven.com/api/public/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: YourProduct/1.2.0 (you@example.com)"
```

```json
{
  "success": true,
  "value": {
    "account": {
      "code": "b41c9e07",
      "displayName": "Cascade Rentals",
      "contextKind": "own-default",
      "role": "OWNER"
    },
    "application": {
      "clientId": "hvci_your_client",
      "name": "Your Product",
      "sandbox": false
    },
    "scopes": ["account:read", "listings:read", "blog:read", "blog:write"],
    "capabilities": {
      "canWrite": true
    },
    "site": {
      "kind": "propertyGroup",
      "code": "7f3a12c9",
      "name": "Smoky Mountain Cabins",
      "url": "https://www.smokymountaincabins.com"
    }
  },
  "error": null
}
```

## Fields worth acting on

**`scopes`** is what you actually hold right now, after intersection with the host's grant and your approved ceiling. It may be narrower than what you requested and narrower than what you held yesterday. Treat it as authoritative rather than trusting your own record of the authorization.

**`capabilities.canWrite`** tells you whether a write will be refused on role grounds before you compose one. A host who authorized you from a read-only seat will have `canWrite: false`, and every write scope you hold is inert. Surface this in your own interface rather than discovering it on first use.

**`account.contextKind`** is one of `own-default`, `member` or `linked`. `linked` means the person who authorized you manages this account through an agency relationship rather than owning it, which is worth knowing because that relationship can be severed independently of anything you or the host do. **`account.role`** is `OWNER`, `MANAGER` or `VIEWER`, re-derived on every request.

**`site`** is the site the host picked for your blog on the consent screen. Haven asks only when you request `blog:write`. `kind` is `propertyGroup` (a collection site — read it with `GET /property-groups/{code}`) or `property` (a single listing — `GET /properties/{code}`). It is `null` when the host was not asked, or the site has since been deleted. It labels the connection; it does not narrow it. See [Blog publishing](05-blog-publishing.md).

**`application.sandbox`** is `true` while your client is in sandbox. The data behind this grant is seeded test data, not a real portfolio.

## What it does not return

The name or email of the person who approved the connection. Any listing, reservation, guest or message. Billing state, subscription plan or payout balance. The other applications this host has connected.

## Using it

Call it once at the start of a sync run rather than before every request; it costs a read against your budget like anything else. Re-read it after any `insufficient_scope` failure, after completing an incremental authorization, and on a schedule slow enough not to matter, so that a narrowing a host performed in your absence does not surprise you mid-run.