FortiGate DNS
FortiGate API token setup: create a VDOM-scoped REST API administrator, restrict it to DNSMigrator's egress IP, and connect to the FortiGate CMDB API over HTTPS.
On this page
FortiGate API token permissions
- Credential type
- REST API token
- Preview access
- Administrator profile: System → Configuration · Read
- Apply access
- Administrator profile: System → Configuration · Read/Write
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "FORTIGATE"
}Create credentials
Create a VDOM-scoped REST API administrator, restrict it to DNSMigrator's egress IP, and connect to the FortiGate CMDB API over HTTPS.
Access you'll grant
Administrator profile: System → Configuration · Read
Administrator profile: System → Configuration · Read/Write
Before you start
- A FortiGate administrator with the super_admin profile; only super_admin can create REST API administrators.
- A public, trusted HTTPS management endpoint that can restrict access to our egress IP.
Setup steps
0 of 6 done
Create a DNS API profile
Go to System → Admin Profiles, select Create New, and under Access Permissions set System → Configuration to Read/Write for apply, or Read for preview only. Leave unrelated groups at no access. The equivalent CLI group is
sysgrp.FortiOS CLI profileconfig system accprofile edit "DNSMigrator" set sysgrp read-write next endCreate a REST API administrator
Go to System → Administrators, select Create New → REST API Admin, assign the new Administrator Profile, and select only the required VDOM (commonly
root). Use a dedicated API identity rather thansuper_admin.Restrict trusted hosts
In Trusted Hosts, add
our egress IP/32as the source allowed to use this token. FortiOS requires a source address and does not allow0.0.0.0/0here. Keep browser CORS disabled unless another integration specifically needs it.Trusted hostour egress IP/32Copy the generated token
Select OK and copy the generated API token immediately. FortiGate shows it only once. Store it as a secret; DNSMigrator sends it in
Authorization: Bearer <token>.Publish HTTPS safely
Make the FortiGate administrative HTTPS service reachable from
our egress IPon a public hostname with a publicly trusted certificate, preferably through a dedicated management interface or tightly restricted proxy. DNSMigrator calls over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses, validates every DNS answer, and pins one validated IP.Enter the VDOM and creation view
Enter the public origin in Management URL, paste the token into REST API token, and set VDOM to the API administrator's VDOM. View for new zones is creation-only: choose Shadow (internal clients) or Public (public clients). Check access before previewing records.
Management URLhttps://fw.example.com:10443
Troubleshooting
403 Forbidden
Confirm our egress IP is in Trusted Hosts, the token's administrator is assigned to this VDOM, and its profile grants System Configuration access.
401 or an invalid API token
Tokens are shown once. Generate a new key with execute api-user generate-key, replace the stored token, and do not enable URL query-key authentication.
The management endpoint cannot be reached
Permit the configured HTTPS port from our egress IP, install a trusted certificate, and ensure the hostname resolves only to public addresses accepted by the guard.
The check passes but apply is denied
The check performs only a GET. Change System → Configuration from Read to Read/Write in the assigned profile, then check again before applying.
Official documentation
- FortiGate: REST API administrator
- FortiGate: using APIs
- FortiGate: administrator profiles
- DNSControl: FortiGate provider
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| Management URLhost | Required | Public HTTPS origin of the FortiGate admin service. Do not append /api/v2/cmdb. |
| REST API tokenapiKey | Required | The API token displayed once when the REST API administrator is created or regenerated. |
| VDOMvdom | Optional | Exact VDOM assigned to the API administrator; leave empty for root. |
| View for new zonesview | Optional | View used only when DNSMigrator creates a DNS database: shadow for internal clients or public for public clients. |
Capabilities
- Create zones
- Yes
- List zones
- Yes
- DNSSEC
- Not available through this connection
- Minimum TTL
- Automatic
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
Caveats
- FortiGates usually sit on private networks: we only connect if the admin HTTPS interface is exposed on a public address with a valid certificate, because private and internal addresses are refused by design.
- Only A, AAAA and CNAME records plus MX at the zone apex are supported; wildcards, TXT, SRV and CAA are not, and disabled entries are left untouched.
- Every change rewrites the zone's whole dns-entry table; we read and merge first so records outside the plan survive, but concurrent edits in the GUI can be overwritten.
Troubleshooting
- 403 Forbidden
- Confirm {egressIp} is in Trusted Hosts, the token's administrator is assigned to this VDOM, and its profile grants System Configuration access.
- 401 or an invalid API token
- Tokens are shown once. Generate a new key with execute api-user generate-key, replace the stored token, and do not enable URL query-key authentication.
- The management endpoint cannot be reached
- Permit the configured HTTPS port from {egressIp}, install a trusted certificate, and ensure the hostname resolves only to public addresses accepted by the guard.
- The check passes but apply is denied
- The check performs only a GET. Change System → Configuration from Read to Read/Write in the assigned profile, then check again before applying.