Quickstart: set up a marketplace app and verify auth

You'll need:

• A HelloBooks marketplace developer account (contact your HelloBooks partner manager if you don't have one)
• A test HelloBooks org + entity to install your app into (your own test tenant is fine)
• curl and jq installed locally for the verification step

This quickstart sticks strictly to endpoints that are live today: /public/v1/health and /public/v1/me. There are no skipped or stubbed steps.

Host placeholder. Examples below use api.hellobooks.com as a stand-in. Replace it with your environment's host — production, staging, and self-hosted deployments each have their own. Confirm the correct host with your HelloBooks contact before going live.

In the HelloBooks marketplace dashboard:

1. Create a new app — give it a slug, display name, and OAuth redirect URI.
2. Note the client_id and client_secret you receive — these identify your app to the OAuth provider.
3. Declare the scopes your app needs (see Scopes). Start with the minimum — users are more likely to install apps that ask for less.

Your marketplace app now exists, but no installs have happened yet — /public/v1/me would return 401 invalid_token because there's no token to send.

Send the user (you, in this case) through the OAuth install flow:

1. Redirect to the HelloBooks authorize URL with client_id, scope, and redirect_uri.
2. The user picks the org + entity to install your app into and approves the requested scopes.
3. HelloBooks redirects back to your redirect_uri with a one-time code.
4. Your server exchanges code (plus client_secret) at the token endpoint, receiving an access_token and refresh_token.

Store the install record on your side: the access_token, refresh_token, the org/entity it was scoped to, and the granted scopes.

The exact OAuth endpoint paths are part of the marketplace OAuth provider — your marketplace developer dashboard documents them. They are not under /public/v1/* (which is for already-issued tokens).

Sanity-check that your token is being accepted at all:

export HB_TOKEN="<access_token>"
curl -i -H "Authorization: Bearer $HB_TOKEN" \
  https://api.hellobooks.com/public/v1/health

You should see:

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 119

{ "ok": true, "ts": 1762800000000 }

If you get 401 invalid_token, your access token is not valid — re-check the install flow, refresh, or re-install.

Now confirm exactly which tenant your token is scoped to:

curl -s -H "Authorization: Bearer $HB_TOKEN" \
  https://api.hellobooks.com/public/v1/me | jq

{
  "install_id": "65f0a1b2c3d4e5f6a7b8c9d0",
  "client_id": "cli_abc123",
  "app_slug": "your-app-slug",
  "org_ref_id": "65a0...",
  "entity_ref_id": "66b1...",
  "scopes": ["invoices:read", "bills:read"]
}

Persist org_ref_id, entity_ref_id, and scopes against this install record locally. Every later request will template URLs from these values (see Tenant Isolation).

As a defense-in-depth check, try a deliberately wrong tenant:

curl -i -H "Authorization: Bearer $HB_TOKEN" \
  https://api.hellobooks.com/public/v1/orgs/aaaaaaaaaaaaaaaaaaaaaaaa/entities/bbbbbbbbbbbbbbbbbbbbbbbb/webhooks

You should see:

HTTP/1.1 403 Forbidden

{ "error": "tenant_scope_violation", "message": "Token not authorized for this org." }

This confirms the tenant guard is enforcing scope, even though your token is otherwise valid. Move on to subscribing to webhook events.