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.

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

{
  "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.

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.