How to authenticate with the DomainCare API using Bearer tokens, manage API keys, and handle auth errors.

Authentication

The DomainCare API uses Bearer token authentication. Every request must include an Authorization header with a valid API key.

Creating a key

Navigate to Settings > API Keys.
Click Create API key.
Enter a name, choose a permission scope, and set an optional expiry.
Copy the key immediately — it cannot be retrieved later.

Keys use the format dc_<32 hex characters>. DomainCare stores a SHA-256 hash of the key, not the key itself.

Permission scopes

Every API key has a scope that controls which operations it can perform:

Scope	Allowed operations
Read only	`GET` — list domains, read events, read check results
Read + Write	`GET` and `POST` — also add new domains
Full access	`GET`, `POST`, and `DELETE` — including domain deletion

Scopes are cumulative: Write includes Read, Full includes Write.

Choose the narrowest scope that fits your use case. For MCP clients and monitoring dashboards, Read only is recommended. A key with insufficient scope returns 403 insufficient_scope.

Using the key

Pass the key as a Bearer token:

curl https://domaincare.io/api/v1/domains \
  -H "Authorization: Bearer dc_abc123..."

Key lifecycle

State	Meaning
Active	Key works normally. `lastUsedAt` updates on each request.
Expired	Past the expiry date set at creation. Returns `401` with error code `key_expired`.
Revoked	Manually revoked from Settings. Returns `401` with error code `key_revoked`.

Revoke a key any time from Settings > API Keys by clicking the revoke button next to the key.

Error responses

Status	Error code	Meaning
`401`	`missing_token`	No `Authorization` header or not in `Bearer <token>` format.
`401`	`invalid_key`	Key not found.
`401`	`key_expired`	Key has passed its expiry date. Create a new key.
`401`	`key_revoked`	Key was manually revoked. Create a new key.
`403`	`api_disabled`	Account is on a free trial, has no active subscription, or subscription is suspended.
`403`	`insufficient_scope`	API key scope too narrow for this operation (e.g. `read` key attempting `POST`).
`429`	`rate_limit_exceeded`	Rate limit exceeded. Wait until `X-RateLimit-Reset`.

All error responses return JSON:

{
  "error": "key_expired",
  "message": "API key has expired. Create a new key in Settings → API Keys."
}

Availability

API access requires a paid plan with an active subscription. Accounts in the following states cannot use the API:

Free trial
No active subscription
Subscription suspended (payment failure beyond the grace period)