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 where your rate limit stands.

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",
      "timezone": "America/Los_Angeles",
      "currencyCode": "USD"
    },
    "application": {
      "clientId": "hvci_your_client",
      "name": "Your Product",
      "sandbox": false
    },
    "connection": {
      "id": "hvgr_9c21f0",
      "connectedAt": "2026-08-31T14:02:11.000Z",
      "lastUsedAt": "2026-08-31T18:44:02.000Z"
    },
    "scopes": [
      "account:read",
      "listings:read",
      "calendar:read",
      "calendar:write"
    ],
    "context": {
      "kind": "own-default",
      "role": "OWNER",
      "canWrite": true
    },
    "rateLimit": {
      "readRemaining": 573,
      "writeRemaining": 118,
      "resetAt": "2026-08-31T18:45:00.000Z"
    }
  },
  "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.

context.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.

context.kind 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.

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.