Authentication
Every API key is a pair created together in the dashboard. They share scopes, expiry and revocation.
| Key | Looks like | Use it for | Send it as |
|---|---|---|---|
| Secret key | sk_live_… | Server-to-server calls. Full access within the key's scopes. | Authorization: Bearer sk_live_… |
| Public key | pk_live_… | Browsers and mobile apps. Only the catalogue endpoints: plans, domain search and domain prices. | X-Public-Key: pk_live_… |
Scopes
A secret key can only call endpoints whose scope it holds. Calls without it fail with 403 insufficient_scope.
| Scope | Allows |
|---|---|
read | Read apps, deployments, databases, domains and billing |
write | Create, update and delete apps, env vars and webhooks |
deploy | Trigger deployments |
domains | Register domains (creates invoices) |
ai | Use 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.