Setup values or an Apple configuration profile for a profile.
const url = 'https://api.opdns.io/v1/setup/apple?profile=example&protocol=doh';const options = { method: 'GET', headers: {cookie: '__Host-opdns_session=<__Host-opdns_session>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.opdns.io/v1/setup/apple?profile=example&protocol=doh' \ --cookie __Host-opdns_session=<__Host-opdns_session>Token scope: profiles:read.
platform=apple returns an Apple configuration profile
(.mobileconfig, application/x-apple-aspen-config, served as an
attachment) with one com.apple.dnsSettings.managed payload: DoH
(ServerURL = the profile’s DoH URL, plus /<device> when device
is given) or, with protocol=dot, DoT (ServerName =
<device>-<id>.<domain> or <id>.<domain>). Payload UUIDs are
stable UUIDv5s of the profile id, protocol and device, and the
payload identifier is the same for both protocols, so reinstalling
replaces the installed profile. No on-demand rules: the settings
apply on every network. When the deployment has a signing
certificate the body is the property list in a DER CMS SignedData
(the certificate chain included), and iOS and macOS show
the profile as “Verified” if the chain reaches a root they trust;
otherwise (or if signing fails) it is the plain property list,
shown as “Unverified”.
Every other platform returns JSON: the profile’s endpoint values for the device and the docs page with the platform’s steps.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Public 6-character id; never 000000.
Device name, sanitised as the resolver does (lowercase, [a-z0-9-], at most 32 characters). A name with no letters or digits is a validation error.
platform=apple only: doh (default) or dot.
Responses
Section titled “Responses”Setup values (JSON) or the configuration profile (platform=apple).
object
The docs site page with this platform’s steps.
The profile’s endpoints; DoH, DoT and DoQ carry the device when one is given, IPv6 and IPv4 addresses never do.
object
The sanitised device name, or null.
Example
{ "platform": "windows", "instructions_url": "https://opdns.io/docs/setup/windows", "values": { "doh": "https://dns.opdns.net/abc123/living-room-tv", "dot": "living-room-tv-abc123.dns.opdns.net", "doq": "living-room-tv-abc123.dns.opdns.net" }}Not authenticated.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/unauthenticated", "title": "Unauthorized", "status": 401, "code": "unauthenticated", "detail": "You're not signed in, or your sign-in has ended. Please sign in again to continue.", "request_id": "5f2c9a0e7b1d4c38"}Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off), email_unverified (creating a profile before the email address is verified).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/insufficient_scope", "title": "Forbidden", "status": 403, "code": "insufficient_scope", "detail": "This API token isn't allowed to do this: it needs the profiles:write scope. Create a token that includes it, then try again.", "required_scope": "profiles:write", "request_id": "5f2c9a0e7b1d4c38"}Unknown platform, or profile not found.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/not_found", "title": "Not Found", "status": 404, "code": "not_found", "detail": "We couldn't find that. It may have been deleted, or the link may be wrong.", "request_id": "5f2c9a0e7b1d4c38"}Field validation failed (validation_failed, unknown_list), or the organisation’s plan does not allow the write (plan_limit, naming the limit in limit).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/validation_failed", "title": "Unprocessable Content", "status": 422, "code": "validation_failed", "detail": "Some of what you sent needs fixing. The list of errors says what to change.", "errors": [ { "field": "settings.block_mode", "message": "one of nxdomain, refused, null, block-page" } ], "request_id": "5f2c9a0e7b1d4c38"}