Authentication, tokens and scopes
The dashboard is the API’s first client and uses no private endpoints: what
it does, you can do. The base URL is https://api.opdns.io, and
the specification is served at
/v1/openapi.yaml.
Two ways in
Section titled “Two ways in”| Method | How | Scopes |
|---|---|---|
| Session | the __Host-opdns_session cookie, set by signing in with your op account (GET /v1/auth/oidc/start in a browser, which goes to opauth.net and back) |
all |
| API token | Authorization: Bearer opdns_… |
the ones chosen at creation |
Browsers use sessions. Scripts and integrations use tokens. A
cookie-authenticated write from an origin other than the dashboard is
rejected (csrf_rejected).
A session lasts at most 30 days from sign-in and ends after 7 days
unused. The first request more than 24 hours after its token was issued
gets a new token in Set-Cookie; the previous one keeps working for a few
seconds, so requests already in flight do not fail. Password sign-in is
slowed after failures (100 ms, doubling up to 5 s per address and per
account); passkey sign-in is not.
Create a token
Section titled “Create a token”In the dashboard: Account → API tokens → New token. Name it, tick the scopes it needs (each one says what it allows), and optionally choose an expiry date: the token stops working at the end of that day. The secret is shown once; store it like a password. Only a signed-in session can create or revoke tokens; a token cannot mint another token.
With the API (session only):
curl -X POST https://api.opdns.io/v1/tokens \ -H 'Content-Type: application/json' \ --cookie "__Host-opdns_session=…" \ -d '{"name":"home-assistant","scopes":["profiles:read","analytics:read"]}'The response holds secret (opdns_ followed by 52 characters) once.
Scopes
Section titled “Scopes”Give a token the fewest scopes it needs. Each operation needs exactly
one scope, or takes a session only (signing out, tokens themselves,
data exports, checkout and the billing portal). The table is generated from the
specification: every operation’s security
names its scope (bearer: [scope]), and the API enforces exactly that
scope.
| Scope | Allows | Operations |
|---|---|---|
profiles:read |
Read profiles and what belongs to them (settings, rules, lists, linked IPs, devices, nodes, list reports, block page certificate) and the setup values. | GET /v1/profiles/{id}/block-page/ca.crt, GET /v1/profiles/{id}/block-page/ca.mobileconfig, GET /v1/profiles/{id}/block-page/ca.pem, GET /v1/profiles/{id}/block-page/ca, GET /v1/profiles/{id}/devices/{deviceId}, GET /v1/profiles/{id}/devices, GET /v1/profiles/{id}/linked-ips, GET /v1/profiles/{id}/list-reports, GET /v1/profiles/{id}/lists, GET /v1/profiles/{id}/nodes, GET /v1/profiles/{id}/rules, GET /v1/profiles/{id}, GET /v1/profiles, GET /v1/setup/{platform} |
profiles:write |
Create, change and delete profiles and what belongs to them (rules, lists, linked IPs and their DDNS tokens, devices, list reports, block page certificate). | DELETE /v1/profiles/{id}/block-page/ca, DELETE /v1/profiles/{id}/devices/{deviceId}, DELETE /v1/profiles/{id}/linked-ips/{linkId}, DELETE /v1/profiles/{id}, GET /v1/profiles/{id}/linked-ips/{linkId}/ddns, PATCH /v1/profiles/{id}/devices/{deviceId}, PATCH /v1/profiles/{id}, POST /v1/profiles/{id}/block-page/ca, POST /v1/profiles/{id}/linked-ips/{linkId}/ddns/rotate, POST /v1/profiles/{id}/linked-ips, POST /v1/profiles/{id}/list-reports, POST /v1/profiles, PUT /v1/profiles/{id}/lists, PUT /v1/profiles/{id}/rules |
nodes:write |
Create self-hosted nodes and their enrolment codes, revoke nodes, and decide about a standalone node’s local profile. | DELETE /v1/profiles/{id}/nodes/{node}, POST /v1/profiles/{id}/nodes/{node}/adoption, POST /v1/profiles/{id}/nodes |
account:read |
Read the account, its plan and usage, its audit log and its API tokens; send dashboard error reports and feedback. | GET /v1/account/plan, GET /v1/auth/audit, GET /v1/auth/me, GET /v1/tokens, POST /v1/client-errors, POST /v1/feedback |
billing:read |
Read the organisation’s billing state (the organisation owner only). | GET /v1/account/billing |
logs:read |
Search and tail the query logs of every profile. | GET /v1/profiles/{id}/logs/stream, GET /v1/profiles/{id}/logs |
analytics:read |
Read the counts, timelines and top lists of every profile. | GET /v1/profiles/{id}/analytics/{shape} |
Reading a DDNS URL is profiles:write, not profiles:read: the URL lets
its holder move a linked address.
Each operation in the reference states its scope.
A token without it gets 403 insufficient_scope, and the problem’s
required_scope names the scope it lacks:
{ "type": "https://opdns.io/problems/insufficient_scope", "title": "Forbidden", "status": 403, "code": "insufficient_scope", "detail": "the token lacks the nodes:write scope", "required_scope": "nodes:write"}An operation that takes a session only answers a token
403 session_required. Tokens see only the profiles of their own
organisation; others are 404, not 403.
When creating and revoking nodes moved from profiles:write to
nodes:write (API 0.45.0), every token that had profiles:write
received nodes:write, so none lost access.
Use a token
Section titled “Use a token”curl -H "Authorization: Bearer $OPDNS_TOKEN" https://api.opdns.io/v1/profilesRevoke a token from the same dashboard page, or DELETE /v1/tokens/{id}
with a session: the next request with it is 401. The dashboard shows
when each token was last used (to the minute) and when it expires; an
expired token is 401 like a revoked one.
Requests with tokens count against your plan’s API rate, shared by every token of your organisation: see Rate limits.
Response headers
Section titled “Response headers”Every response carries X-Request-Id, the
X-Opdns-Api-Version
header, and security headers meant for browsers:
Content-Security-Policy (default-src 'none'; frame-ancestors 'none'
and more), X-Frame-Options: DENY, Referrer-Policy: no-referrer,
X-Content-Type-Options: nosniff, and Strict-Transport-Security wherever
the session cookie is marked Secure (every deployment but development).
Node tokens
Section titled “Node tokens”Self-hosted nodes use a separate credential, the node token
(opdnsnode_…), obtained by exchanging a one-time enrolment code at
POST /v1/nodes/enrol. It is accepted only by the node endpoints and the
link. See Enrol a node.