|
| 1 | +--- |
| 2 | +title: Oracle NetSuite Service Account |
| 3 | +description: Configure certificate-based OAuth 2.0 client credentials once and reuse them across NetSuite blocks |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Step, Steps } from 'fumadocs-ui/components/steps' |
| 8 | +import { FAQ } from '@/components/ui/faq' |
| 9 | + |
| 10 | +Oracle NetSuite authenticates SuiteTalk machine-to-machine clients with a signed JWT and a certificate mapping. Sim stores the SuiteTalk URL, Client ID, Certificate ID, and private key as one encrypted service-account credential. Every NetSuite block stores only that credential's ID; Sim signs the assertion and injects the short-lived access token on the server. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +- A dedicated NetSuite integration role with **REST Web Services** and **Log in using OAuth 2.0 Access Tokens**, plus the record and SuiteAnalytics permissions your workflows require. |
| 15 | +- An integration record with **Client Credentials (Machine to Machine) Grant** and the **REST Web Services** scope enabled. |
| 16 | +- A 3072- or 4096-bit RSA key pair, or a P-256, P-384, or P-521 EC key pair, and a public certificate generated through your organization's certificate process. |
| 17 | +- Access to **OAuth 2.0 Client Credentials (M2M) Setup** and **Company URLs** in the target NetSuite environment. |
| 18 | + |
| 19 | +<Callout type="warn"> |
| 20 | +Create and map credentials separately in production, sandbox, and Release Preview. A sandbox refresh removes its OAuth 2.0 client-credential mappings, and each environment has a different authoritative SuiteTalk URL. |
| 21 | +</Callout> |
| 22 | + |
| 23 | +## Configure NetSuite |
| 24 | + |
| 25 | +<Steps> |
| 26 | + <Step> |
| 27 | + In **Setup → Company → Enable Features**, enable **REST Web Services** and **OAuth 2.0**. Enable **SuiteAnalytics Workbook** if workflows will use datasets. |
| 28 | + </Step> |
| 29 | + <Step> |
| 30 | + Create a dedicated integration role and grant only the record, transaction, subsidiary, and analytics permissions the workflows need. Avoid using Administrator. |
| 31 | + </Step> |
| 32 | + <Step> |
| 33 | + Under **Setup → Integration → Manage Integrations**, create or edit an integration, enable the machine-to-machine client-credentials grant and REST Web Services scope, then save its **Client ID**. |
| 34 | + </Step> |
| 35 | + <Step> |
| 36 | + Upload only the public certificate under **OAuth 2.0 Client Credentials (M2M) Setup**. Map it to the integration, entity, and dedicated role, then save the generated **Certificate ID**. Keep the private key outside NetSuite. |
| 37 | + </Step> |
| 38 | + <Step> |
| 39 | + Under **Setup → Company → Company Information → Company URLs**, copy the complete **SuiteTalk (SOAP and REST Web Services)** URL for this environment. |
| 40 | + </Step> |
| 41 | +</Steps> |
| 42 | + |
| 43 | +Oracle documents the [role setup](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771510070.html), [integration record](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html), [certificate requirements](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_162755332391.html), and [client-credential mapping](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html). |
| 44 | + |
| 45 | +## Add the Credential to Sim |
| 46 | + |
| 47 | +<Steps> |
| 48 | + <Step> |
| 49 | + Add an **Oracle NetSuite** block to a workflow and open the **NetSuite Account** dropdown. |
| 50 | + </Step> |
| 51 | + <Step> |
| 52 | + Choose to add a credential, then enter the authoritative SuiteTalk URL, Client ID, Certificate ID, and PEM private key that matches the uploaded certificate. |
| 53 | + </Step> |
| 54 | + <Step> |
| 55 | + Save the credential. Sim validates the URL and key policy, signs a client assertion, and performs a real token exchange before storing the encrypted credential. |
| 56 | + </Step> |
| 57 | +</Steps> |
| 58 | + |
| 59 | +The private key is encrypted at rest and is never returned through the token endpoint or injected into a workflow tool. At execution time, Sim resolves the selected credential to a short-lived bearer token and the normalized SuiteTalk origin. |
| 60 | + |
| 61 | +## Use Pickers and Manual Values |
| 62 | + |
| 63 | +Selecting the credential enables these account-backed fields: |
| 64 | + |
| 65 | +| Field | Lists | Additional scope | |
| 66 | +| --- | --- | --- | |
| 67 | +| Record Type | Up to 1,000 record types visible in the metadata catalog | credential | |
| 68 | +| SuiteAnalytics Dataset | The first 1,000 datasets visible to the role | credential | |
| 69 | +| Async Task | Up to 100 tasks belonging to a known batch job | job ID | |
| 70 | + |
| 71 | +Picker results reflect the selected role's permissions. Switch any picker to Advanced mode to type an identifier or reference an upstream output. Record IDs, job IDs, transform targets, actions, fields, forms, subresources, and relationship IDs remain manual because NetSuite does not expose a bounded universal listing that would make those choices complete and reliable. |
| 72 | + |
| 73 | +## Rotate or Revoke |
| 74 | + |
| 75 | +To rotate a certificate, create and upload the replacement certificate, create the new NetSuite mapping, then reconnect the existing Sim credential with the new Certificate ID and private key. Reconnecting changes the encrypted credential fingerprint, so later executions mint against the new material. |
| 76 | + |
| 77 | +After confirming workflows succeed, remove the old certificate mapping in NetSuite. Deleting a Sim credential removes its workflow bindings but does not revoke the corresponding NetSuite certificate mapping. |
| 78 | + |
| 79 | +<FAQ items={[ |
| 80 | + { question: "Why can’t I paste the key into each block?", answer: "The signing key is long-lived account material. Keeping it in one encrypted credential avoids duplicating it in workflow state and lets every block reuse the same verified account connection." }, |
| 81 | + { question: "Why is my picker empty?", answer: "The pickers use the selected integration role. Confirm that role can access the metadata catalog, datasets, or async job, then use Advanced mode when you already know an identifier." }, |
| 82 | + { question: "Can one credential access production and sandbox?", answer: "No. Each environment has its own SuiteTalk URL and client-certificate mapping. Create one Sim credential per environment." }, |
| 83 | + { question: "Why did the credential stop working after a sandbox refresh?", answer: "NetSuite clears OAuth 2.0 client-credential mappings during a sandbox refresh. Recreate the mapping and reconnect the Sim credential with its new Certificate ID." }, |
| 84 | + { question: "Does deleting the credential revoke it in NetSuite?", answer: "No. Remove the certificate mapping in NetSuite as well when decommissioning or responding to a compromise." }, |
| 85 | +]} /> |
0 commit comments