Authentication

The API authenticates requests with an API key sent as a Bearer token. Keys belong to your organization and carry fine-grained scopes for zones, records and the Monitor.

Bearer keys

Send your key in the Authorization header on every request:

Authorization header

Authorization: Bearer qfx_1a2b3c4d_kJ8x...

A complete request looks like this:

cURL

curl "https://api.monitor.quathos.com/v1/orgs/$ORG_ID/zones" \
  -H "Authorization: Bearer $QUATHOS_KEY"

Keep secrets server-side

An API key grants access to your organization's DNS: a leaked key can redirect your domains. Use it only from your backend, never from browser or mobile clients. If a key leaks, revoke it immediately from the dashboard.

Base URL and organization

All endpoints live under a single versioned prefix. Requests and responses are JSON (Content-Type: application/json), and every resource path is scoped to your organization: /orgs/{org_id}/….

Base URL

https://api.monitor.quathos.com/v1

A key only works on the organization that issued it. Any other org_id answers 404 org_not_found, the same as an organization that does not exist.

Key format

Every key starts with the qfx_ prefix followed by an 8-character public identifier and the secret part: qfx_1a2b3c4d_<secret>. Only the prefix is shown in listings: the API keeps a hash of the full key, never the key itself.

Creating a key

Keys are created from the dashboard, under API Keys (/painel/tokens), or with POST /orgs/{org_id}/api-keys from a dashboard session (see Kubernetes). It takes the owner or admin role in the organization and a verified e-mail. Pick the scopes the key needs and, optionally, the zones it may touch.

Shown once

The full key secret is displayed only once, at creation. We store just a hash: if you lose it, create a new key and revoke the old one.

The API key object

Field	Type	Description
`id`	integer	Unique identifier of the key.
`prefix`	string	Public, non-secret prefix (`qfx_` + 8 hex chars) used to identify the key in listings.
`scopes`	string[] \| null	Scopes granted to the key. Omitting it at creation grants the four DNS scopes; the Monitor scopes are opt-in.
`allowed_zone_ids`	integer[] \| null	Zones the key may touch. `null` means every zone of the organization; any other zone answers `404 zone_not_found`, as if it did not exist.
`last_used_at`	datetime \| null	When the key last authenticated a request.
`revoked_at`	datetime \| null	When the key was revoked; `null` while active.
`created_at`	datetime	Creation timestamp (UTC).
`secret`	string	The full key. Present only in the creation response, never again.

Scopes

A key only reaches what its scopes allow. Grant the least you need: a key that only manages records doesn't need zone:write. Omitting scopes grants the four DNS scopes, the historical default.

The two Monitor scopes are never granted by omission. A scope that arrived by default would quietly widen every key created without an explicit list, including scripts written months ago that nobody re-reviewed. Ask for them on purpose, and only where the automation needs them: adding a watched domain consumes plan quota and starts continuous probing of someone else's network on your behalf.

Scope	Type	Description
`zone:read`	scope	List zones, read zone details and setup, check delegation.
`zone:write`	scope	Create, import and delete zones; verify ownership.
`record:read`	scope	List the records of a zone.
`record:write`	scope	Create, update and delete records.
`acme`	scope	Create and delete only the TXT records at `_acme-challenge`, for certificate issuance. See Kubernetes.
`monitor:read`	scope	Read watched domains, their checks, the host inventory and the service checks.
`monitor:write`	scope	Add and verify watched domains, manage hosts, switch service profiles on and off, accept expected changes.

DNSSEC is the exception: its routes accept only a dashboard session today, so no scope reaches them. See DNSSEC.

Revoking a key

Revoke a key at any time from the dashboard. Revocation is immediate (the key stops authenticating on the next request) and permanent: revoked keys cannot be re-enabled, so create a new one instead.

Best practices

One key per integration or environment: rotation stays painless and the blast radius of a leak stays small.
Store keys in a secret manager or environment variables, never in source control.
Prefer narrow scopes and zones: record:write alone is enough for dynamic-DNS style updates, and allowed_zone_ids keeps it to one domain.
Watch last_used_at in the dashboard to spot stale keys and retire them.

Dashboard sessions

The dashboard signs in with its own user session; that flow is not part of the integration surface. As an integrator, API keys are all you need, except to issue keys and to manage DNSSEC, which take the session token.

Previous Kubernetes Next Errors