How Should You Rotate FormKiQ API Keys?

Create a replacement, verify every consumer and confirm the old key is rejected

Published

Navy-and-teal glass illustration of a replacement credential, a verified document integration and an old credential switched off.
Plan the replacement, prove consumer access and verify revocation.

A nightly document import succeeds with its new API key. The next morning, a retry worker fails because it still has the old credential in memory. Creating a replacement was straightforward; proving that every consumer had switched was the missing step.

For planned rotation, create a replacement, update each consumer, verify its real FormKiQ operations, then revoke and test the old key. Set an overlap deadline and an accountable owner. If a key is suspected of exposure, use the incident process to revoke it promptly and restore service with a replacement; do not wait for the normal observation window.

Confirm the authentication route before changing a secret

FormKiQ exposes different authentication endpoints: HttpApiUrl for JWT, IamApiUrl for AWS SigV4 and KeyApiUrl for FormKiQ API keys. An administrator uses the appropriate JWT-authenticated administration route to manage keys. The integration sends its API key in the Authorization header to the key-authenticated endpoint.

For workloads that can use FormKiQ's IAM route, assess temporary role credentials before introducing a long-lived API key. AWS recommends temporary credentials for workloads. Changing the endpoint alone does not add SigV4 signing. Browser applications should normally use the documented JWT approach, with service keys kept in trusted back-end processes.

Make the change in three controlled stages

  1. 1. Prepare

    Identify consumers and grants

    Record every worker, scheduled job, environment, site, group and required operation.

  2. 2. Replace

    Deploy and verify

    Store the new credential securely, refresh each consumer and test the operations it needs.

  3. 3. Revoke

    Prove the old key fails

    Delete the previous key, check its rejection and confirm the replacement still works.

FormKiQ operations and the application evidence needed for a planned rotation. Retain references and results without retaining credential values.
CheckpointFormKiQ operationEvidence to retain
Create the replacementPOST /sites/{siteId}/apiKeys with an approved name, groups and permission configuration.Internal credential alias, intended site, approved grants, owner and managed-secret version.
Verify each consumerRepresentative authorised calls through KeyApiUrl, using the replacement.Consumer deployment, loaded secret version, operation result and request reference.
Revoke the old keyDELETE /sites/{siteId}/apiKeys/{apiKey} through the authorised administration route.Revocation time and outcome, old-key rejection and replacement-key success.
Reconcile the inventoryGET /sites/{siteId}/apiKeys and consumer-side configuration review.Every consumer accounted for, unexplained failures assigned and the rotation record closed.

Check the API-key request reference against the installed backend when selecting grants. Groups and permissions must support the intended work without broadening access just to make a test pass. The deletion route contains the credential value, so redact administration request URLs as well as authorisation headers and response bodies.

Verify that every consumer loaded the replacement

Updating a secret does not prove that a warm worker, scheduled job or retry process has loaded it. Record the secret version used by each deployment without logging its value. Refresh or restart consumers according to their actual loading behaviour. A rarely scheduled job needs an explicit verification plan within the overlap window.

Exercise a small, authorised operation representative of each consumer. For an import adapter, verify document creation and any retrieval or metadata operations it requires using controlled evidence. A generic health endpoint is insufficient if it never calls FormKiQ. Keep failed business validation, wrong-endpoint requests and network failures distinguishable from credential rejection.

After deletion, test the old key against a known previously permitted request on the same endpoint, and confirm that the replacement succeeds there. A timeout alone is not proof of revocation. If a write's outcome is uncertain, reconcile the operation before retrying it so the credential change does not create duplicate business records.

Worked example: supplier-evidence import and its retry worker

This fictional integration imports supplier certificates into the Vendor and Supplier Document Management workflow. A scheduled importer and a retry worker share a managed-secret reference. Their site and document permissions are configured for that process.

  1. Record the complete consumer inventory

    The integration owner identifies both workers, their deployed versions, endpoint, site and required operations. Procurement's VEN-1042 supplier file supplies a representative workflow: new evidence is collected, reviewed and accepted through the application.

  2. Create and store the replacement

    An administrator creates a new site-scoped API key using the approved group and grant configuration. The key goes directly into the managed secret store. The rotation record contains its internal alias and secret-version reference, without the key value.

  3. Refresh and exercise both workers

    The importer loads the replacement and a controlled certificate handoff succeeds. The retry worker still reports the earlier secret version, so the owner refreshes it and verifies its normal operation too. Both results are recorded before planned revocation.

  4. Revoke and verify

    The administrator deletes the old key. A controlled check confirms that it is rejected while the replacement continues to perform the permitted operation. Procurement's certificate review remains a separate business decision; the rotation does not mark evidence approved.

  5. Close the change with recovery evidence

    The owner checks the next scheduled run and retry queue for unexplained failures, reconciles uncertain writes and closes the rotation record. If configuration needs repair after deletion, the team fixes the replacement or issues another key. Restoring an old secret version does not recreate a deleted API key.

The Vendor and Supplier Business Solution provides the evidence, review and renewal workflow. Its external import mappings and interface are scoped configuration and integration. Business Solutions and selected Integration Frameworks are separately scoped offerings for Advanced and Enterprise; this key-lifecycle procedure also applies to other server-side FormKiQ API consumers.

Handle suspected exposure as an incident

A planned overlap is for a credential that remains trusted. Suspected exposure changes the priority: revoke promptly, identify the affected site and operations, review activity and recover consumers under the incident plan. Record the service impact rather than extending a compromised key's life to preserve normal scheduling.

Key revocation also has a boundary. It does not retrieve copies already downloaded, and should not be treated as revocation of every previously issued S3 URL. The presigned-document URL guide explains their separate signing-credential, expiry and containment controls. Include issued links in the incident assessment when relevant.

Rotation checklist

  • Confirm the authentication mode, endpoint, target site and integration owner.
  • Inventory scheduled jobs, warm workers, retries, environments and secret-loading behaviour.
  • Review required groups and grants against the installed backend's supported permissions.
  • Set the planned overlap deadline and verify every consumer uses the replacement.
  • Record representative operation results without logging keys, tokens or signed URLs.
  • Delete the old key and prove its rejection alongside replacement-key success.
  • Reconcile uncertain writes, remaining failures and post-revocation recovery steps.
  • Use prompt revocation and the incident process when a credential may be exposed.

Prove the replacement works and the old key is rejected

A completed rotation accounts for every consumer and both sides of the credential change. Use the documented FormKiQ operations, verify the application's actual access and retain enough redacted evidence to explain the result. Keep planned rollout and emergency containment as distinct procedures.

      Start with FormKiQ Core

      The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.

      Get Started Free

      Deploy FormKiQ Essentials or Advanced

      Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.

      Explore Options

      Plan an Enterprise Rollout

      For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.

      Book a Call