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_…
- Cache the token and reuse it until it expires — re-mint on expiry or on a
401 invalid_token, never per request. The token endpoint is rate-limited; minting in a request loop will hit429. - Credentials go in the request body (shown above, the spec's required method); HTTP Basic on the token endpoint is also accepted. Never both in one request, and never in the URL.
scopeis optional: omitted, the token carries all the key's scopes; pass a space-separated subset (e.g.scope=storefront) to mint a narrower token.- Errors follow the spec:
invalid_client,invalid_request,invalid_scope,unsupported_grant_typeas JSON. No refresh tokens — under this grant your client simply authenticates again. - Tokens are opaque — don't parse them. A leaked token dies within the hour; a leaked secret must be rotated.
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');
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.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:
| Scope | Grants |
|---|---|
storefront | Read the catalogue, availability and quotes. |
gateway | Live availability + create / cancel / modify reservations. |
ingest | Push 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
- Server-to-server only. The key must never reach a browser, a mobile app binary, or client-side JavaScript.
- Store the secret in your server's environment, never in code or version control.
- Rotate by requesting a second key, switching traffic, then revoking the old one — both are valid during the overlap, so rotation needs no downtime.
- Failed key authentication returns
401; do not retry it — a bad secret never heals by retrying. A401withWWW-Authenticate: Bearer … error="invalid_token"is different: your access token expired — mint a fresh one and retry once.
429 means back off
and retry after a delay; sustained polling should live in your scheduled refresh, not in per-visitor requests.