NewHost Docs

Authentication

Every API key is a pair created together in the dashboard. They share scopes, expiry and revocation.

KeyLooks likeUse it forSend it as
Secret keysk_live_…Server-to-server calls. Full access within the key's scopes.Authorization: Bearer sk_live_…
Public keypk_live_…Browsers and mobile apps. Only the catalogue endpoints: plans, domain search and domain prices.X-Public-Key: pk_live_…
NewHost stores only a hash of the secret key, so it is shown once when you create it. If you lose it, create a new key and revoke the old one. Never put a secret key in client-side code or a public repository.

Scopes

A secret key can only call endpoints whose scope it holds. Calls without it fail with 403 insufficient_scope.

ScopeAllows
readRead apps, deployments, databases, domains and billing
writeCreate, update and delete apps, env vars and webhooks
deployTrigger deployments
domainsRegister domains (creates invoices)
aiUse the AI gateway (spends AI credits unless you use your own provider key)

Keys always act for the account that created them and can only reach that account's data.

Public keys in the browser

Public-key endpoints send CORS headers, so you can call them from a web page, for example to power a domain search box on your own site. Add your site's origins to the key (e.g. https://shop.example.co.za); requests from any other origin are then refused.

Domain search from the browser

const res = await fetch("https://api.newhost.co.za/v1/domains/check?q=" + encodeURIComponent(name), {
  headers: { "X-Public-Key": "pk_live_..." },
});
const { data } = await res.json(); // [{ domain, available, premium, price }]

Safe retries with Idempotency-Key

A request that creates or changes something should carry an Idempotency-Key when it may be retried: a timeout, a dropped connection or a 502 is not proof that the change did not happen. Send a value of your own (a UUID or an order reference), 1 to 200 printable characters without spaces, on POST, PUT, PATCH and DELETE.

A create that is safe to retry

curl -X POST https://api.newhost.co.za/v1/apps \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 4f0c2a9e-create-shop" \
  -H "Content-Type: application/json" \
  -d '{"name":"shop"}'

The first call runs and its answer is stored for 24 hours. A retry with the same key and the same body gets that stored answer back, with Idempotent-Replayed: true, and changes nothing. The same key with a different body is refused with 409 idempotency_conflict; use a new key for a new request. A retry that arrives while the first call is still running (your client timed out, the server didn't) gets 409 idempotency_in_progress and changes nothing: retry with the same key a few seconds later to get the first call's answer. A 5xx is never stored, so a retry after a real failure runs again. Answers over 100 KB (long deployment pages) are not stored.

Expiry and revocation

  • Choose an expiry (30 days, 90 days, a year or never) when creating a key. Expired keys return 401.
  • Revoke a key in the dashboard at any time; it stops working immediately.
  • The dashboard shows when each key was last used, which helps you find keys that are safe to remove.
  • Keys don't ask for the dashboard's two-factor sign-in: a secret key works on its own, so keep it as safe as a password and give it only the scopes it needs.