Skip to content
Log inDashboard

Overview

Control plane REST API for opdns profiles, accounts and tokens.

The dashboard is the first client; there are no private endpoints. Operator (admin) routes are not part of this API: they are a separate API on an internal host, and every former /v1/admin path answers 404 here.

Authentication: a session cookie (__Host-opdns_session, set by the sign-in callback GET /v1/auth/oidc/callback after signing in with an op account at opauth; opdns_session on a plain-HTTP dev server, where the __Host- prefix is impossible) or an API token sent as Authorization: Bearer opdns_.... Tokens carry scopes (profiles:read, profiles:write, nodes:write, account:read, billing:read, logs:read, analytics:read; described on the bearer scheme’s x-opdns-scopes); sessions have every scope. Every operation’s security names the one scope a token needs for it (bearer: [scope]); an operation without bearer takes a session only (403 session_required for a token). A token without the scope gets 403 insufficient_scope whose required_scope names it. Cookie-authenticated writes from another origin are rejected unless the origin is an allowed dashboard origin.

CORS: the three public signup surfaces (/v1/auth/signup-mode, /v1/waitlist, /v1/waitlist/confirm) allow exact configured origins, their route’s method and Content-Type only. Eligible preflights answer 204; a rejected origin, method or header answers 403. Actual responses name the origin and allow credentials. Other /v1 routes add Access-Control-Expose-Headers: ETag, Retry-After, X-Request-Id, Content-Disposition, Location for an allowed dashboard origin. Their preflights answer 204 without authentication; unallowed origins get no CORS headers. Responses vary on Origin on those routes, and on signup surfaces when Origin is present.

Errors are RFC 9457 problem documents (application/problem+json) with a stable machine code.

Profile writes are optimistic: every profile resource returns an ETag holding the profile version, and writes accept If-Match with it (412 on mismatch). Every write bumps the version and publishes the full profile document to the edge.

Unauthenticated routes are rate limited per client IP (429 with Retry-After). Requests with an API token are limited per organisation, across every token of its members and every server, to the plan’s api_requests_per_minute (GET /v1/account/plan) in fixed one-minute windows. Every response to a token carries RateLimit-Limit (the plan’s requests per window), RateLimit-Remaining (left in this window) and RateLimit-Reset (seconds until the window resets), as in the IETF RateLimit header fields draft, and RateLimit-Policy (<limit>;w=60). Past the limit the answer is 429 rate_limited with Retry-After (the same seconds as RateLimit-Reset). Dashboard sessions are not counted.

Lists are cursor-paginated: limit (default 50, at most 200) and cursor (the next_cursor of the previous page, opaque); next_cursor is null on the last page. Order is stable, so rows created between pages are never repeated or skipped before the cursor. A modified cursor is a 400 invalid_cursor.

POSTs that create something take an Idempotency-Key header: a repeat with the same key and request within 24 h replays the first (2xx) response with Idempotent-Replayed: true instead of creating again; the key reused with a different request is a 409 idempotency_key_reused, and a repeat while the first is still running a 409 idempotency_in_progress. Keys are per account.

Sessions last at most 30 days from sign-in and end after 7 days unused; the first request more than 24 h after the session token was issued gets a new token in Set-Cookie (the previous one stays valid for a few seconds).

Sign-in: opdns signs everyone in through opauth, the op account (account.opauth.net), with OIDC; credentials, verification, recovery and address changes are the op account’s. API token creation, node creation, exports and account deletion need a sign-in at opauth within the last five minutes (reauth_required): the dashboard signs in again with prompt=login. Emailed links point at the dashboard; a one-time token travels in the URL fragment, which browsers never send to a server, and the dashboard asks before it submits one (a link opened by a mail scanner changes nothing). An account still unverified seven days after its first sign-in is deleted.

Versioning. Every route is under /v1. Before the public beta the API changes as the product does: endpoints and fields are added, changed, renamed and removed without a deprecation period, and the dashboard and opdns’s own clients change with them in the same release. info.version is this document’s version: it changes with every change to the document (minor for any change to the contract, removals included; patch for wording), and every response carries it in the X-Opdns-Api-Version header (also api_version in GET /v1/meta). The API changelog says what changed in each version. Clients should ignore response fields they do not know and treat an enum value they do not know as “other”.

Session cookie set by sign-in. Named opdns_session on a dev server over plain HTTP, where browsers refuse the __Host- prefix.

Security scheme type: apiKey

Cookie parameter name: __Host-opdns_session

API token (opdns_...) with scopes. An operation names the one scope a token needs in its security (bearer: [scope]); x-opdns-scopes lists every scope a token can carry.

Security scheme type: http

Node token (opdnsnode_...) from POST /v1/nodes/enrol, for the node-side endpoints.

Security scheme type: http