Skip to content
Log inDashboard

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.

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.

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):

Terminal window
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.

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.

Terminal window
curl -H "Authorization: Bearer $OPDNS_TOKEN" https://api.opdns.io/v1/profiles

Revoke 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.

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).

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.