A NetSuite OAuth client-credentials certificate rotation should prove that every dependent runtime can obtain authorized access with the replacement before the old certificate is retired. Track the integration, entity, role, certificate and deployed consumers as one change. A successful test from one developer's machine does not establish that the scheduled production jobs have switched.
This runbook is for a planned rotation. Suspected credential exposure requires the organization's security-response process, which may prioritize immediate revocation over a continuity-first overlap. Only authorized administrators and application owners should perform credential changes.
Define the rotation scope
List the exact account, environment, integration record, mapped entity and role. Identify every application deployment that uses the certificate: active workers, standby workers, scheduled jobs, reporting services and deployment pipelines where applicable.
Record the current certificate identifier, expiry, approved secret-storage reference and operating owner. Do not copy private keys or access tokens into the runbook. The document should remain useful to reviewers without granting them credential access.
Confirm whether a supplier manages part of the connection. Agree who creates the replacement material, who registers it, who changes the runtime and who verifies the business flow. A renewal reminder sent to an administrator is not a complete ownership model.
Check the current certificate requirements
Oracle specifies certificate format, supported key sizes and a maximum validity period for the OAuth client-credentials flow. Its certificate guidance also describes expiry notifications to administrators and the binding between certificate, integration, role and entity. Use those current requirements when preparing the replacement.
At the time of review, Oracle states a maximum validity of two years and notifications at two months, one month and fourteen days before expiry. Treat those notifications as an additional control. Maintain your own accountable renewal process so that a missed email does not become the first sign of a production failure.
Verify the applicable active-certificate capacity and the state of existing mappings before planning an overlap. Do not remove an unfamiliar certificate merely to make room; establish which consumer depends on it.
Obtain the approved change and recovery plan
The change request should state the certificate mapping, dependent flows, planned window, validation steps and retirement condition. Identify who can authorize rollback before the old certificate is retired and what happens if the replacement fails afterward.
Decide whether a staged deployment is possible. A small, controlled canary can demonstrate the replacement while other consumers continue under the approved transition plan. If the platform requires all workers to restart together, account for that interruption and the queued work.
Keep normal rotation separate from access expansion. Changing the key does not justify adding subsidiaries, records or administrative permissions to the integration role.
Prepare and register the replacement securely
Generate and store the signing material through the organization's approved process. Register the public certificate against the correct integration, entity and role. The private key remains protected in the authorized runtime's secret store.
Oracle documents a programmatic certificate-management endpoint for appropriately permitted users. Its operations include listing, adding and revoking certificates, with a valid access token and the required scope. A controlled administrator-led process can also be used where appropriate.
If the team uses the API, follow the current operation contract. Oracle's add-certificate reference identifies the certificate content, role and entity parameters. Verify those values against the approved change before submission.
Capture the new certificate identifier and validity in the runbook. Keep only nonsecret evidence needed for review.
Update a controlled runtime and obtain fresh access
Change the runtime's approved secret reference and certificate identifier as required by its implementation. Confirm that it targets the intended account and integration record.
The validation must obtain fresh access through the replacement configuration. A request that succeeds using an already cached token may not prove that the new certificate is working. Ask the developer or platform owner to demonstrate the actual token-acquisition path without exposing token values.
Run a low-risk permitted operation and an appropriate prohibited-access test. The role boundary should remain unchanged. Then run a representative business flow through the authorized test or canary process and reconcile its outcome.
A NetSuite integration support plan should specify how this evidence is collected when a managed connector hides the token exchange from the customer.
Move all consumers and verify the next scheduled run
Update every runtime listed in the scope. Include paused schedules and standby deployments that may not run during the change window. Record the deployment or configuration version for each consumer.
Verify more than a manual health check. Let the next meaningful scheduled job run, or perform an authorized equivalent test, and confirm that it can acquire access through the replacement. Inspect authentication errors, queue age and completed business events.
If a consumer fails, determine whether it still references the old certificate, reads an outdated secret version or points to a different account. Do not repeatedly regenerate certificates without identifying the configuration mismatch.
Keep a checklist with one row per consumer and evidence for configuration, fresh authentication and business completion. The rotation remains incomplete while a production dependency is unverified.
Retire the old certificate only after the exit check
For a routine planned rotation, the retirement decision should require verified consumer migration, stable business processing and an agreed observation window. Reconfirm the exact certificate to revoke.
Oracle's certificate-list endpoint returns information including certificate identity, validity and revocation state. Use supported account evidence to confirm the final mapping state and retain a nonsecret record of the change.
Do not rely only on successful API requests that were authenticated before retirement. Validate the relevant fresh-authentication behavior under the approved test plan. The security owner should determine the appropriate checks for outstanding tokens and the application's authorization model.
Update expiry monitoring, remove obsolete runtime references through the authorized process and preserve required change evidence. Do not leave an old private key in an untracked deployment folder after the active configuration has moved.
A hypothetical missed standby worker
A business rotates the certificate for an order integration. Its active worker obtains access with the replacement, and normal processing continues. The inventory also shows a standby worker used during maintenance.
The standby configuration still references the old certificate. A controlled failover test catches the mismatch before retirement. The platform owner updates that configuration and repeats the fresh-authentication and order-reconciliation checks.
Without that test, the rotation could appear complete until a later outage activates the standby worker. This hypothetical example shows why consumer inventory and failover verification belong in the runbook. It does not claim that every platform supports the same failover procedure.
Keep an emergency path ready
If the signing material may be compromised, follow the approved incident process. The security owner decides whether to revoke immediately, isolate affected consumers and replace access. Business continuity work then proceeds within that containment decision.
The incident runbook should identify the flows that will stop, the people to notify, the approved workaround and the evidence needed to reconcile work after access is restored. Avoid restoring compromised credentials simply because the old configuration is familiar.
Include both planned and emergency procedures in NetSuite support documentation, with current owners and supplier contacts.
Frequently asked questions
Does one successful API request prove the new certificate works
Not necessarily. The application may be using cached access. Verify fresh token acquisition through the replacement configuration and a representative business operation.
Should the role change during certificate rotation
Only if a separate, explicit access change has been approved. A routine key replacement should preserve the authorized business scope.
Can a planned overlap be used during a security incident
The security-response owner must decide. Suspected exposure may require immediate revocation, even if that creates an interruption. Do not apply the routine continuity plan automatically.
Which consumers are easiest to miss
Standby workers, paused jobs, month-end schedules, supplier-managed deployments and old runtime instances. Inventory and test them before retiring the previous certificate.
What evidence closes the rotation
Correct replacement mapping, verified fresh authentication for all dependent consumers, reconciled business processing, confirmed old-certificate retirement and updated monitoring and ownership records.
