DNSAFE MSP Portal Docs

Platform Overview#

DNSAFE is a DNS-layer security platform built for Managed Service Providers. You deploy our resolvers as the upstream DNS for your clients' networks, and all queries flow through our filtering engine before being answered. Threats, malware, phishing, and custom-blocked domains are intercepted at the DNS level — before a connection is ever made.

The platform has two portals and a REST API:

Key Concepts

• Partner — An MSP or reseller account. Partners own tenants and are billed per-tenant on a monthly plan.
• Tenant — A client network protected by DNSAFE. Each tenant has its own block/allow rules, IP mappings, and query logs.
• IP Mapping — Associates a client IP or CIDR range with a tenant so the resolver knows which policy to apply.
• IP Group — A named collection of IPs within a tenant that can have their own separate ruleset (e.g. a school's student lab vs. staff network).
• ThreatGrid — DNSAFE's threat intelligence blocklist, aggregated from several public and commercial threat feeds. Applied platform-wide.

How a lookup is filtered#

Every DNS lookup from a protected network goes through the same steps, in this order:

Changes you make in the portal reach the resolvers within about 5 minutes — no restart needed.

Quickstart Checklist#

Follow these steps to get a client network protected from scratch. Each step links to the relevant section.

1. 1
   Create a Partner accountLog in to portal.dnsafe.net → Infrastructure → Partners → + Add Partner. Set the plan, contact email, and optional white-label branding.
2. 2
   Add a TenantInfrastructure → Tenants → + Add Tenant. Assign the tenant to the partner you just created.
3. 3
   Map the client's IP addressesOpen the tenant → IPs tab → add the client's public IP or CIDR range. This tells the resolver which policy to apply to that network.
4. 4
   Point the client's DNS to DNSAFEConfigure the client's router or firewall to use 3.12.124.91 as their upstream DNS. For encrypted DNS, use DoH or DoT (see DNS Setup).
5. 5
   Verify queries are flowingSecurity → Query Logs — filter by the tenant. Within a minute of the client making any DNS request you should see activity appear.
6. 6
   Configure filtering rulesOpen the tenant → Rules tab. Add domain block and allow rules as needed, or set up scheduled rules for time-based access control.
7. 7
   Enable add-on packs(Optional) Open the tenant → Add-ons tab to enable extended filtering categories like adult content, social media, or ads & trackers.

Partner Accounts#

Partners are the top-level entities in the DNSAFE hierarchy. Each partner represents an MSP, reseller, or distribution channel. Partners own tenants and are billed on a monthly plan based on the number of active tenants.

Plans

Extra tenants are counted on active tenants and added to the plan at each monthly renewal, with no charge for part of a month. Switched-off tenants don’t count. Current prices: dnsafe.net/pricing.

Creating a Partner

Navigate to Infrastructure → Partners → + Add Partner. Fill in:

• Name — The partner's business name (shown in the portal and on invoices)
• Email — Primary contact and billing email
• Plan — Starter, Growth, or Enterprise

Onboarding Progress

Each partner card shows a 5-step onboarding checklist. This tracks whether the partner has completed: account creation, first tenant added, client IP mapped, first query logged, and first custom rule configured. Use this to identify partners who haven't fully activated.

Partner API Keys

Partners create their own API keys in the portal under API Keys. A key acts as the partner that created it and can only reach that partner’s tenants. See API Keys below and the API reference.

Tenant Management#

A tenant represents a single client network. Each tenant has isolated rules, IP mappings, and query logs. Multiple tenants can belong to the same partner.

Creating a Tenant

Go to Infrastructure → Tenants → + Add Tenant. You'll need to select the partner this tenant belongs to and give the tenant a name (typically the client's company name).

Tenant Detail View

Clicking a tenant opens the detail view with tabs:

Disabling a Tenant

Disabling a tenant stops DNS filtering for that network — queries will no longer be matched against the tenant's rules or the ThreatGrid blocklist. The tenant's IPs remain mapped but are inactive. Use this for temporary offboarding or billing holds rather than deleting the tenant.

IP Mapping#

IP mapping is how the DNS resolver identifies which tenant a query belongs to. When a lookup arrives, the resolver matches the client’s public IP to a tenant and applies that tenant’s rules. Lookups from IPs that aren’t registered to any tenant or account are refused, so a network must be mapped before it can use DNSAFE.

Adding IP Addresses

Open a tenant → IPs tab → + Add IP. You can enter:

• Single IPv4 — e.g. 203.0.113.42
• IPv4 CIDR range — e.g. 203.0.113.0/24
• Single IPv6 — e.g. 2001:db8::1

IP Conflicts

The same IP cannot be mapped to two different tenants simultaneously. If you attempt to add an IP that's already assigned to another tenant, you'll receive a conflict error. You must remove it from the existing tenant first.

Dynamic IPs

For clients whose public IP changes (residential or small business connections):

• Auto-update (recommended): on the network's IP Addresses list, click Auto-update → Turn on for a single IP. You get a private link for the client's router (Dynamic DNS with a custom URL, add ?ip= plus the router's address placeholder) or for a scheduled task on an always-on PC or Mac. The list shows when it last ran and what happened; you get a notice whenever it changes the IP. Treat the link like a password; New link replaces it.
• Change: edit the IP in place. It keeps its note, history and auto-update link. Changes are recorded in the Activity log.
• If someone opens the portal from the office on a new address, it offers to switch the network to it (after they confirm they're there). The portal, sign-in and your white-label portal domain always load on that network, even before the IP is updated.
• Use a CIDR range that covers the ISP's IP pool for that client
• Add the client’s laptops and phones as Roaming devices (see DoH / DoT). Each gets its own encrypted DNS setup, so it’s recognised whatever IP it’s on

Propagation Time

New or changed IP mappings reach the resolvers within about 5 minutes.

IP Groups#

IP Groups let you apply different filtering policies to different segments of the same tenant's network. For example, a school might have one group for student devices (strict filtering) and another for staff (relaxed filtering).

Creating a Group

Tenant detail → Groups tab → + New Group. Give it a name, then add the IPs or CIDR ranges that belong to it. These IPs must already be mapped to the parent tenant.

Group Rule Priority

When an IP belongs to a group, the resolver applies rules in this order:

1. Group allow rules (highest priority — explicitly allowed)
2. Group block rules
3. Group scheduled rules
4. Tenant allow rules
5. Tenant block rules
6. Tenant scheduled rules
7. Global ThreatGrid blocklist (lowest priority)

DNS Resolver Setup#

Configure your clients to use the following resolver addresses. The client's router, firewall, or DHCP server should hand out these addresses as the upstream DNS.

Standard DNS (UDP/TCP port 53)

Per-Platform Configuration

DNS-over-HTTPS (DoH) & DNS-over-TLS (DoT)#

DNSAFE supports encrypted DNS for clients that need privacy or where port 53 is blocked.

With these plain addresses, encrypted lookups are matched to tenants by the client’s public IP, so the network must be registered.

Roaming devices (per-device DNS IDs)

For laptops and phones that leave the office, open the tenant in the portal and use Roaming devices → Add device. Each device gets its own 8-character ID and is matched to the tenant by that ID instead of its IP, on any network:

The portal shows the steps for each device type: a profile link for iPhone, iPad and Mac, Private DNS for Android, and the DoH template for Windows 11 and Chromebook. Each roaming device counts as one IP on the plan. If a device is lost or its setup is shared, use Reset its setup: the old ID stops working at once. Lookups from roaming devices show in the logs as Roaming device <id>.

Browser DoH Configuration

How Blocking Works#

Policy decisions are made in memory on the resolver, in well under a millisecond, so filtering adds no noticeable delay.

When a website is blocked, the lookup returns the address of the DNSAFE block page, so people see a “This site has been blocked” message instead of a browser error. Partners can brand that page with their own name and support email (see White-Label). Other lookup types for a blocked name get an empty answer.

Rules, IP mappings and groups you change in the portal are pushed to the resolvers automatically about every 5 minutes.

Block & Allow Rules#

Custom rules let you extend or override the default ThreatGrid filtering for individual tenants. Rules apply to the entire tenant unless scoped to an IP group.

Adding a Rule

Tenant detail → Rules tab → + Add Rule. Enter the domain and select Block or Allow.

• Block — Blocks this domain (and its subdomains) for all IPs in the tenant.
• Allow — Explicitly passes this domain even if it appears in the ThreatGrid blocklist. Useful for whitelisting a legitimate site that's been incorrectly flagged.

Domain Format

Enter bare domains without http:// or paths:

• ✅ tiktok.com — blocks the domain and all subdomains
• ✅ ads.example.com — blocks only this subdomain
• ❌ https://tiktok.com/feed — paths are stripped automatically

Bulk Rule Import

For large rule sets, use the REST API. POST /api/tenant/{id}/rules accepts a JSON array of domain/action pairs and is significantly faster than adding rules one at a time through the UI.

Scheduled Rules#

Scheduled rules allow you to block or allow a domain only during specific time windows on specific days of the week. This is useful for scenarios like blocking social media during school hours or allowing gaming sites only on weekends.

Creating a Scheduled Rule

Tenant detail → Rules tab → + Add Rule → Scheduled. Configure:

• Domain — The domain to block or allow
• Action — Block or Allow
• Days — Select which days the rule is active (e.g. Mon–Fri)
• Time window — Start and end time in the tenant's local timezone

How It Works

Scheduled rules are stored in .sched files in pipe-delimited format:

domain|action|days_bitmask|start_minute|end_minute

The resolver checks the current time (US Eastern) on every lookup and checks if the query falls within the rule's active window. Days are encoded as a bitmask (Mon=1, Tue=2, Wed=4, Thu=8, Fri=16, Sat=32, Sun=64).

Time Zone

Scheduled rules run in the server's timezone (UTC by default). When configuring time windows through the portal, times are entered and displayed in the browser's local timezone and converted automatically.

Group Rules#

Group rules work identically to tenant-level rules but apply only to IPs that are members of a specific IP group. This lets you have different policies for different departments, floors, or device categories within the same tenant network.

Example Use Cases

• K-12 school: Student group blocks social media and gaming; staff group allows them
• Office: Guest Wi-Fi group applies strict filtering; employee group is more relaxed
• Retail: POS terminal group blocks everything except payment processor domains

Manage group rules from: Tenant detail → Groups tab → open a group → Rules.

ThreatGrid Blocklist#

ThreatGrid is DNSAFE's aggregated threat intelligence blocklist. It's applied to every DNS query across the entire platform — for all tenants — regardless of their custom rules.

Feed Sources

The combined blocklist covers about 2.5 million domains and is refreshed automatically every night. DNSAFE’s own domains are never blocked.

Override with Allow Rules

If a domain is in the ThreatGrid blocklist but you need to allow it for a specific tenant (e.g. a legitimate internal tool that was incorrectly flagged), add an Allow rule for that domain on the tenant. Tenant allow rules take priority over the global blocklist.

Dashboard Feed Status

The dashboard Overview page shows the ThreatGrid Feed card including last update time, sources, and refresh interval. If it hasn’t updated in over a day, contact support.

Add-on Packs#

Add-on packs add filtering categories to a tenant, on top of ThreatGrid. Each pack is billed per tenant per month; the price is shown before you confirm.

Enable or disable packs from Tenant detail → Add-ons. Changes reach the resolvers within about 5 minutes.

Query Logs#

Every DNS query processed by DNSAFE is logged with full context. Logs are accessible in real time from the portal and via the REST API.

Accessing Logs

Two entry points:

• Security → Query Logs — All queries across all tenants, with tenant and partner filters
• Tenant detail → Logs tab — Scoped to a single tenant

Filters

Log Fields

Live Mode

Toggle Live in the top-right of the Query Logs page to enable automatic refresh every 5 seconds. Useful for watching queries in real time during a client setup or troubleshooting session.

Export

Click Export CSV to download the current filtered log set. The export includes all columns and respects active filters. For large exports or automated reporting, use the REST API GET /api/logs endpoint.

Tenant Health#

The Tenant Health page (Operations → Tenant Health) gives a real-time view of every tenant's activity status. It auto-refreshes every 30 seconds.

Status Definitions

Alerts

DNSAFE sends email alerts when a tenant goes offline or experiences a threat spike. Configure alert thresholds and recipients in Settings → Notifications. Alerts include a 1-hour cooldown to prevent flooding.

Domain Intelligence#

The Domain Intelligence scanner (Security → Domain Intel) lets you run a comprehensive threat analysis on any domain. It's useful for investigating suspicious queries in your logs or vetting a domain before adding a rule.

What It Checks

• DNS records — A, AAAA, MX, NS, TXT, CNAME
• RDAP registration — Registrar, creation date, expiry, registrant org
• Geo-IP — Country, ASN, hosting provider for each resolved IP
• ThreatGrid match — Whether the domain is in the current blocklist
• Query history — How often this domain has been queried on your network and with what actions
• Risk score — 0–100 composite score based on domain age, geo, flags, and threat feed matches

Risk Score Bands

Scans are rate-limited to 50 per day on Starter/Growth plans. Enterprise plans have unlimited scans.

Alerts & Notifications#

Configure automated alerts in Settings → Notifications. Alerts are sent via email to the address on your account.

API Keys#

The REST API lets you manage tenants, IPs, groups and rules and read query logs from your own tools. Create keys in the portal under API Keys — the full key is shown once, so store it somewhere safe.

API Key Tiers

Authentication

Send the key as a bearer token on every request:

Authorization: Bearer dnsapi_…

Base URL

https://api.dnsafe.net/api/v1

Endpoints, parameters and examples are in the API reference.

Plans & Billing#

DNSAFE billing is managed through Stripe. Partners are billed monthly based on their plan and active tenant count. Add-on packs are billed as metered usage per tenant per month.

Billing Cycle

Usage is reported to Stripe daily. Invoices are generated at the end of each billing period. You can download invoices and update your payment method from Settings → Billing or via the Stripe billing portal link.

Overage

If your tenant count exceeds your plan's limit, the portal will notify you. Additional tenants cannot be added until you upgrade. Contact support to discuss a custom Enterprise arrangement if your Growth plan limit is insufficient.

Trialing

New partners enter a trial period. During the trial, all features are available with no charge. The partner card in the portal shows the number of trial days remaining. Once the trial expires, a valid payment method is required to continue.

🏷️White-Label & Custom Domains#

Partners can present the DNSAFE portal under their own brand — custom domain, logo, colors, and support email. Clients see your company's identity throughout the portal and on the DNS block page. Custom domain provisioning (SSL + reverse proxy) is fully automated.

What gets branded

Branding fields

Custom domain setup — step by step

1. Open the Branding tab
   Go to Partners → [Partner] → Branding tab. Click Edit Branding.
2. Fill in your branding fields
   Upload your logo and enter your Company Name, Support Email and colors. These take effect immediately after saving — no domain required.
3. Enter your custom domain
   In the Custom Domain field type the subdomain you want to use, e.g. protect.acmeit.com. Use a subdomain (not a root domain). Click Save Branding.
4. Add a CNAME record at your DNS provider
   Log in to your registrar or DNS provider (Cloudflare, Route 53, GoDaddy, Namecheap, etc.) and create:

   TYPE   NAME                    VALUE               TTL
   CNAME  protect.acmeit.com.     custom.dnsafe.net.  300

   Propagation typically takes 1–10 minutes. You can verify with:

   dig CNAME protect.acmeit.com +short
   # should return: custom.dnsafe.net.

5. Provision the domain
   Back in the portal, click ⚡ Provision Domain. DNSAFE will:
   • Verify the CNAME record resolves to the correct server
   • Issue an SSL/TLS certificate via Let's Encrypt
   • Configure the nginx reverse proxy to serve the portal at your domain
   The status badge updates automatically. The whole process takes under 60 seconds if DNS has propagated.
6. Share with your clients
   Once the status badge shows Active, your branded portal is live. Share the URL with your clients — they sign in at your custom domain and see your branding throughout.

Domain status reference

Troubleshooting

MFA & Duo Setup#

DNSAFE supports Duo Security for multi-factor authentication on the MSP portal. MFA can be required for individual partners or enforced platform-wide for all admin logins.

Enabling Duo for a Partner

Partner detail → Security tab → Duo MFA → Enable. Enter the partner's Duo application credentials:

• Integration Key (DXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)
• Secret Key
• API Hostname (e.g. api-xxxxxx.duosecurity.com)

Once enabled, users logging in under that partner will be redirected to Duo for a second factor after entering their password.

Platform-Wide MFA

Admin Settings (gear icon, admin only) → Security tab → toggle Require MFA for all admin logins. This enforces Duo for all users regardless of partner-level settings.

Consumer Accounts#

The consumer portal (my.dnsafe.net) is a self-service portal for home and personal users. Consumer accounts are separate from partner/tenant accounts and are managed independently.

As an admin you can view all consumer accounts from Infrastructure → Consumers. This shows plan, device count, subscription status, and join date.

Consumer Plans

Suspending a Consumer

From the Consumers list, click Suspend on a consumer row to immediately disable their account. Their device IPs are removed from the consumer IP map and queries will no longer be filtered. Use this for billing issues or ToS violations.

Consumer Rules#

Consumer accounts can manage their own block and allow rules from the consumer portal (my.dnsafe.net/rules). These rules apply to all registered devices on their account.

Consumer rules are kept separate from tenant rules and are pushed to the resolvers about every 5 minutes.

As an admin you can view a specific consumer's rules from their detail page (Infrastructure → Consumers → open consumer → Rules tab).

Troubleshooting#

Queries not appearing in logs

1. Confirm the client's DNS is actually pointing to 3.12.124.91 — run nslookup dnsafe.net from the client and check the server shown
2. Check that the client's egress IP is mapped to a tenant (Infrastructure → Tenants → the tenant → IPs tab)
3. Check that the tenant is active (not disabled)
4. Wait up to 5 minutes for the IP map sync cycle

A domain isn't being blocked

1. Verify the rule exists on the correct tenant (not a different one)
2. Check the domain format — enter just the domain, no http:// prefix
3. Wait for the 5-minute sync cycle
4. Try flushing the client's DNS cache: ipconfig /flushdns (Windows) or sudo dscacheutil -flushcache (macOS)
5. Use Domain Intelligence to confirm the domain isn't appearing as allowed somewhere in the rule chain

A blocked domain is showing up as allowed

Check the rule priority chain: group allow rules override tenant blocks. If the querying IP is in a group that has an allow rule for the domain, the block won't fire. Check the group's allow list first.

The block page isn't showing

The block page appears when the browser loads the blocked site and lands on DNSAFE’s block page instead. HTTPS sites will show a certificate warning rather than the page, which is expected. Some browsers cache previous DNS answers for longer. Try a hard refresh or open an incognito window. Also check that the client's router doesn't have DNS rebind protection blocking the response.

API returning 401 Unauthorized

Your API key may have been rotated or the Authorization header format is incorrect. Ensure you're passing: Authorization: Bearer YOUR_KEY (note the space after Bearer).

ThreatGrid feed not updating

Check the dashboard — the ThreatGrid Feed card shows the last update time. Feeds refresh once a day; if it’s more than a day old, contact support.

Frequently Asked Questions#

Can a client IP be mapped to multiple tenants?

No. Each IP can only belong to one tenant at a time. If you need different policies for different subnets, use CIDR ranges that don't overlap, with each range mapped to its own tenant.

How quickly do rule changes take effect?

Rule changes are saved immediately and reach the resolvers within about 5 minutes. DNS resolvers also cache responses — clients may need to flush their DNS cache for the change to take immediate effect.

Does DNSAFE log the full DNS query including all subdomains?

Yes. Every query is logged with the exact domain queried (including any subdomain), the resolved action, client IP, and timestamp.

What happens if the DNSAFE resolver is unreachable?

If the resolver is unreachable, DNS queries will fail and clients will experience internet outages (DNS is required for nearly all internet traffic). Configure a secondary DNS — either a second DNSAFE resolver IP if available on your plan, or a fallback like your ISP's DNS as a secondary only. Note that a secondary DNS will bypass DNSAFE filtering.

Can I use DNSAFE alongside an existing firewall DNS policy?

Yes. DNSAFE operates at the DNS layer and is complementary to firewall rules. DNS filtering is faster (blocks at query time before any connection) and easier to manage for domain-based policies. Use your firewall for IP/port-level controls and DNSAFE for domain-level filtering.

Are query logs retained indefinitely?

Log retention depends on your plan. Contact support for your plan's specific retention policy. For compliance requirements, use the REST API to export logs to your own storage on a scheduled basis.

Can partners log in to the MSP portal directly?

Yes. Partners use the same portal.dnsafe.net login. The portal automatically scopes their view to their own tenants — they cannot see other partners' tenants or admin-level settings.