Authentication

The Hostwise API uses OAuth 2.1 (client credentials grant). Your brand holds one credential — a client_id / client_secret pair, issued when the brand is created. Your backend exchanges it for a short-lived access token, and every API call carries that Bearer token — the long-lived secret itself only ever travels to the token endpoint. The credential identifies your brand: Hostwise resolves your account and your published listings from it — you never send an account id, and you can never see another brand's data, even on the same account.

OAuth 2.1 — client credentials grant

Conforms to draft-ietf-oauth-v2-1. Your backend POSTs its credentials to the token endpoint and receives a Bearer token valid for one hour; resource calls then carry the token, and the long-lived secret only ever travels to one endpoint.

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=…&client_secret=…

// 200 — Cache-Control: no-store
{ "access_token": "alpy_at_…", "token_type": "Bearer",
  "expires_in": 3600, "scope": "storefront gateway ingest" }

Then on every API call:

Authorization: Bearer alpy_at_…

The token client — copy it

Framework-free, Node 18+. Mints once, caches until 5 minutes before expiry, de-dupes concurrent mints, and re-mints exactly once on a 401. This is the same client Hostwise's own brand integrations run in production — copy it as-is:

export function alpyTokenSource({ base = 'https://hostwise.fr', clientId, clientSecret }) {
  let cached = null, inflight = null;
  const url = base.replace(/\/+$/, '') + '/api/oauth/token';
  async function mint() {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'content-type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({ grant_type: 'client_credentials',
        client_id: clientId, client_secret: clientSecret }),
    });
    const data = await res.json().catch(() => null);
    if (!res.ok || !data?.access_token) throw new Error(`token mint ${res.status}: ${data?.error || ''}`);
    cached = { value: data.access_token,
      expiresAt: Date.now() + (data.expires_in - 300) * 1000 };   // renew 5 min early
    return cached.value;
  }
  return {
    async get(force = false) {
      if (force) cached = null;
      if (cached && Date.now() < cached.expiresAt) return cached.value;
      if (!inflight) inflight = mint().finally(() => { inflight = null; });
      return inflight;
    },
  };
}

// fetch() with the token attached and ONE re-mint + retry on 401.
export async function alpyFetch(tokens, url, init = {}) {
  const attempt = async (force) => fetch(url, { ...init,
    headers: { ...(init.headers || {}), authorization: `Bearer ${await tokens.get(force)}` } });
  let res = await attempt(false);
  if (res.status === 401) res = await attempt(true);
  return res;
}

// usage
const tokens = alpyTokenSource({ clientId: process.env.ALPY_CLIENT_ID,
                                 clientSecret: process.env.ALPY_CLIENT_SECRET });
const res = await alpyFetch(tokens, 'https://hostwise.fr/api/storefront/listings');
Bearer tokens only on API calls. Resource requests do not accept the raw key — Authorization: Basic … on an API route returns 401 with a WWW-Authenticate: Bearer challenge. The secret authenticates in exactly one place: the token endpoint (body credentials as shown, or HTTP Basic there if you prefer, per the spec). One credential surface instead of every route — and a leaked request header now dies within the hour instead of being the permanent secret. The secret is stored hashed on Hostwise's side and cannot be recovered — if it is lost, a new key is issued.
The API is HTTPS-only, and plaintext API calls are refused, not redirected. Base64 is encoding, not encryption — TLS is what protects the credential in transit. A client that mistakenly calls http:// would transmit the header in cleartext before any response arrives, so Hostwise answers such calls with 403 instead of a redirect: the mistake fails loudly on your first development request instead of silently working forever. Always configure your base URL as https://hostwise.fr.

Scopes

Keys carry least-privilege scopes. A key is valid only for the doors it was given:

ScopeGrants
storefrontRead the catalogue, availability and quotes.
gatewayLive availability + create / cancel / modify reservations.
ingestPush bookings your site created into Hostwise.

A request with a valid key but a missing scope returns 403. Gateway URLs also carry your brand slug in the path (/api/gateway/:brand/…) — the slug must match the key's brand, or the request is refused with 403 brand mismatch. The credential itself is the boundary; the path is a cross-check.

Rules

Rate limits apply per route (typically 600 requests/minute). A 429 means back off and retry after a delay; sustained polling should live in your scheduled refresh, not in per-visitor requests.