Preserve a newly generated OPNsense API key secret through handoff

Bottom line: Arrange custody before generating the credential. Record who owns the key and where an authorized operator can retrieve it, then make replacement the plan for a lost secret rather than promising later recovery.

Source fact: what the authority says

The OPNsense Local Users and Groups guide places API keys under individual users for machine-to-machine interaction with the product. Creating a key pair downloads a file containing the key and secret. Assigned keys appear in the user’s API Keys tab, where keys no longer used can be removed. The secret’s private part is generated only once, and losing it requires generating a new key pair.

What the source does not establish

This article covers the documented generation, custody and replacement decision. It does not establish an API permission model, an automatic overlap period or a guarantee that removing a key has been tested against every consuming system.

Applicability questions

• Which user owns the key and which automation actually consumes it?
• Who may retrieve the downloaded secret through the approved storage process?
• Which non-secret identifier will link the user, key and consuming job?
• Who can replace the credential and verify the consumer without printing it?

DSE recommendation: controlled next steps

The following steps are DSE recommendations based on the cited source.

DSE recommends naming the user owner and automation owner before generating the key pair. Arrange a protected destination for the downloaded file and a controlled secret-store reference for the consumer. Keep the value out of tickets, source repositories, screenshots and ordinary troubleshooting output.

Use a proposed dedicated test consumer to rehearse the handoff. Have the intended operator obtain the secret through the approved process rather than forwarding it in an unprotected message. Record the consumer configuration reference and owner separately from the secret itself.

Prepare a lost-secret procedure that creates and deploys a replacement pair through the same controlled path. Review the consuming job’s own update and rollback process without inventing a product-provided grace period. Decide when the previous key may be removed only after the authorized replacement check is complete.

Review the assigned-key list with the responsible owners during maintenance. Mark an unidentified key for investigation instead of deleting it immediately because its description is unfamiliar. Preserve the non-secret relationship between the user and automation so offboarding does not rely on one administrator’s memory.

Verification and evidence

Proposed verification: generate a test key through the documented user interface, store it through the approved route and run a harmless authorized API operation from the intended consumer. Preserve only sanitized operation results and controlled reference names. Have another authorized operator confirm that the retrieval instructions are sufficient.

Rehearse replacement with a second test pair and verify the consumer after the reviewed configuration change. Remove the old test key only within that plan and record the subsequent old-key observation separately. Retain failures and cleanup status without collecting credential values in the evidence package.

Official references

• OPNsense — Local Users & Groups — official product documentation; confirm the installed release and configuration.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.