Information
- License: Source First License 1.1
- OpenAPI version:
3.1.0
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