Backing Up Fortinet Configurations via API

Overview

Auvik supports retrieving full configuration backups from FortiOS devices using the REST API. This method provides a reliable way to capture device settings without requiring CLI access.

If Auvik can retrieve a backup through the API, it prioritizes the API method.

When the FortiGate Shows a Successful Backup but Auvik Has No Version

A successful backup or configuration-export message in the FortiGate logs does not necessarily mean that Auvik received and stored the configuration.

Auvik supports FortiGate configuration backups from the Global or root context. VDOM-specific configuration backups are not supported.

Verify the FortiGate context

Confirm that:

• The backup is being performed from the Global or root context.
• The API administrator is not restricted to a single VDOM.
• The API administrator can access the Global or root configuration.
• The account has sufficient read permissions to retrieve the complete configuration.
• The account does not require MFA or an interactive authentication challenge.
• FortiGate Trusted Hosts include the Auvik Collector’s source IP.

When Backups Succeed on Some FortiGates but Fail on Others

It is common for one FortiGate to back up successfully while similar devices fail. Differences in administrative scope, VDOM configuration, firmware, network paths, or security controls can produce inconsistent results.

Compare the working and failing FortiGates using the checklist below.

1. Compare administrator scope and VDOM access

• Use an equivalent Global or root-scope administrator profile on each FortiGate.
• Avoid VDOM-restricted users for backups.
• Confirm that devices using VDOM-specific accounts are not being tested against a Global or root-context backup requirement.

2. Compare credentials and authentication behavior

Confirm that each backup account:

• Has permission to read the complete configuration.
• Does not require MFA, SSO, or another interactive authentication prompt.
• Is not interrupted by an interactive login banner or confirmation prompt.
• Is assigned to the expected administrator profile.

3. Compare Trusted Hosts and access policies

For each FortiGate:

• Confirm the Auvik Collector’s source IP is included in Trusted Hosts.
• Confirm the Collector can reach the management interface over the required protocol.
• Verify that routing, firewall policies, and NAT are consistent with the working device.
• Confirm the correct management IP and interface are configured in Auvik.

4. Compare firmware and device configuration

Different FortiOS versions or enabled features may change prompts, command output, or API behavior.

Compare:

• FortiOS versions.
• Administrator profiles.
• VDOM configuration.
• SSH and HTTPS settings.
• Enabled security or inspection features.
• Backup method and credential assignment.

5. Check device performance and timing

High CPU or memory utilization, rate limiting, or DoS policies can interrupt long-running configuration exports.

If multiple backups run at the same time:

• Stagger backup schedules where possible.
• Avoid running backups during peak device utilization.
• Check for concurrent-session limits or management-plane restrictions.

6. Test network stability

Packet loss or latency between the Collector and a particular site can interrupt the retrieval of large configurations.

From the Collector network, verify that the backup user can:

• Authenticate to the FortiGate.
• Maintain a stable SSH or HTTPS session.
• Retrieve the complete configuration.

7. Compare a failing device with a working device

Document the differences between the two devices, including:

• Administrator or API username.
• Global/root or VDOM scope.
• Trusted Hosts.
• Management IP and interface.
• Routing and NAT.
• FortiOS version.
• Collector assignment.
• Backup method.
• Time and result of the backup attempt.

After making adjustments

1. Re-run the backups on the affected FortiGates.
2. Confirm that new configuration versions appear in Auvik.
3. If failures continue, provide Support with per-device timestamps, the administrator or API username used, the Collector details, and a comparison with a working FortiGate.

Verify Collector connectivity

The Auvik Collector must be able to communicate with the FortiGate management interface over the required protocol:

• SSH for CLI-based collection.
• HTTPS for API-based collection.

Also confirm that:

• Firewall policies and NAT allow the connection.
• Outbound TLS traffic from the Collector to Auvik is permitted over TCP 443.
• Any configured proxy permits large uploads and does not time out.
• SSL inspection or certificate validation is not interrupting the HTTPS session.

Verify the backup in Auvik

1. Open the FortiGate device in Auvik.
2. Open the Configuration or Backups area.
3. Check for a timestamped configuration version.
4. Review device activity or backup logs for retrieval or upload errors.
5. After correcting connectivity or permissions, retry the backup from Auvik.

If the FortiGate log shows that the configuration was exported successfully but no version appears in Auvik, the Collector may have retrieved the configuration but failed to upload or classify it.

Information to provide Support

If the backup still does not appear, provide:

• FortiGate device IP address.
• FortiOS version.
• Auvik site and Collector name.
• FortiGate context used for the backup.
• API or service-account username shown in the FortiGate log.
• Exact timestamp of the successful export, including time zone.
• Relevant FortiGate and Collector error messages.

Required API permissions

The FortiGate REST API administrator must use an Administrator Profile with the following permissions:

• System Configuration: Read/Write
• All other sections: Read
• REST API Access: Enabled

CLI access is optional and is not required for API-based configuration backups.

These permissions are controlled through the Administrator Profile assigned to the REST API administrator.

Why System Configuration requires Read/Write access

The FortiGate configuration backup operation requires System Configuration = Read/Write. Other sections can remain set to Read.

The System Configuration permission is required for Auvik to initiate and retrieve the configuration backup artifact. This does not mean that the API administrator needs write access to every FortiGate configuration area.

The minimum profile should be:

• System Configuration: Read/Write
• All other sections: Read
• REST API Access: Enabled

Verify permissions before testing a backup

Before testing a backup:

1. Confirm the API token is active.
2. Confirm the token is assigned to the expected Administrator Profile.
3. Test a simple read-only API request to verify connectivity.
4. Trigger or wait for a configuration backup.
5. If the read-only request succeeds but the backup returns 401 or 403, confirm that System Configuration is set to Read/Write.

A FortiGate administrator should make changes to the Administrator Profile and REST API administrator. No end-user instructions need to be removed.

Create or edit the Administrator Profile

1. Log in to the FortiGate web interface using an account with Super_Admin privileges.
2. Go to System > Admin > Profiles.
3. Create a new profile or edit the profile assigned to the REST API administrator.
4. Configure the profile as follows:
   • Set System Configuration to Read/Write.
   • Set all other sections to Read.
   • Enable REST API Access.
5. Save the profile.

Create the REST API administrator

1. Go to System > Admin > Administrators.
2. Click Create New.
3. Set the administrator type to REST API Admin.
4. Assign the Administrator Profile created for Auvik.
5. Generate and securely store the API key.
6. Save the new administrator.

If Trusted Hosts are configured, include the Auvik Collector’s source IP address.

Configure the credentials in Auvik

1. Open the affected FortiGate device in Auvik.
2. Update or assign the Fortinet Device API credentials.
3. Enter the FortiGate API key.
4. Test the credentials.
5. Save the credential configuration.

Confirm that the credential is assigned to the correct device and has not been disabled or replaced by another credential.

Validate the backup

1. Confirm the FortiGate is managed in Auvik.
2. Confirm the Device API credential is assigned and active.
3. Trigger or wait for the next configuration backup.
4. Open the configuration backup history.
5. Confirm that a new backup appears and completes successfully.

When viewing the configuration backup, the API administrator appears as the source instead of a CLI user.

Troubleshooting

If the backup fails:

• Confirm System Configuration is set to Read/Write.
• Confirm all other required sections are set to Read.
• Confirm REST API Access is enabled.
• Confirm the REST API administrator is assigned to the correct profile.
• Confirm the API key was copied correctly and has not been regenerated or revoked.
• Confirm HTTPS administrative access is enabled on the interface used by the Auvik Collector.
• Confirm the Collector IP is included in the FortiGate Trusted Hosts list.
• Confirm the Collector can reach the FortiGate over HTTPS, normally TCP 443.
• Check FortiGate logs for denied API requests.
• Check for session limits or rate limiting.
• Confirm the FortiOS version is supported by Auvik.

A 401 or 403 response generally indicates an invalid token, insufficient permissions, an incorrect Administrator Profile, or a Trusted Hosts restriction.

For additional troubleshooting, see Troubleshooting Fortinet device API credentials.