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_…`

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.

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. An administrator's key cannot reach other customers' 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 }]

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.