[$250] NetSuite - Can't connect to NetSuite: role permission error

[applause-bot]

If you haven’t already, check out our contributing guidelines for onboarding and email contributors@expensify.com to request to join our Slack channel!

---

Version Number: v9.4.21-2
Reproducible in staging?: Yes
Reproducible in production?: Yes
If this was caught during regression testing, add the test name, ID and link from BrowserStack: https://test-management.browserstack.com/projects/2219752/folder/13176904/test-cases/41237411
Email or phone of affected tester (no customers): -
Issue reported by: Applause Internal Team
Bug source: Regression TC Execution
Device used: Ventura / Chrome
App Component: Other

Action Performed:

Precondition: Control workspace with enabled Accounting.

1. Go to accounting
2. NetSuite > Connect > enter credentials

Expected Result:

Integration connected.

Actual Result:

Connection failed with an error.

Assume it's because new role name in Expensify - Workspace admin - instead of old name, Admin. NetSuite don't know such role.

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome Safari

Screenshots/Videos

Bug7193663_1782666010437.REC-20260628195531.mp4

View all open jobs on GitHub

Applause Internal Information
Exported by: Julia Ponikarchuk
Bug ID: 7193663

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022071302868806242255
• Upwork Job ID: 2071302868806242255
• Last Price Increase: 2026-06-28

[applause-bot]

While Applause doesn't embed attachments for this bug, here are the links for quick view:
https://platform.applause.com/services/links/v1/external/d9b52c59cf579fabc19fd6b47bc59867bb0fe5c6fe218e4b4129b8d7a6108af0

[MelvinBot]

Issue Analysis

Root Cause: This is a backend NetSuite integration issue, not an App-side bug. When you connect NetSuite, the App only forwards the raw credentials — netSuiteAccountID, netSuiteTokenID, and netSuiteTokenSecret — to the server via the CONNECT_POLICY_TO_NETSUITE command. The App sends no role name at all. The "role permission error" is returned by NetSuite to Expensify's backend integration during the token-based authentication handshake, so the failure originates entirely server-side.

On the reporter's hypothesis: The Expensify policy-role rename ("Admin" → "Workspace admin") is unrelated to this error. The role referenced in a NetSuite "role permission" failure is the NetSuite role assigned to the integration token within NetSuite itself (configured in the customer's NetSuite account), not an Expensify role string. The two are separate systems; the App never passes an Expensify role to NetSuite.

Recommended next step: Because the fix (if any) lives outside the App repository, this needs an internal engineer to investigate the backend NetSuite integration and the connection logs for this attempt. Things worth checking server-side:

• The exact error/jsonCode NetSuite returned during the connect handshake.
• Whether the NetSuite token's assigned role has the required permissions (Token-Based Authentication, Log in using Access Tokens, REST/SOAP web services, etc.).
• Whether anything recently changed in how the backend authenticates the NetSuite connection.

Investigation details

• App connect command and payload: src/libs/actions/connections/NetSuiteCommands.ts:20-46 — builds parameters from credentials and calls API.write(CONNECT_POLICY_TO_NETSUITE, ...).
• Payload type (no role field): src/libs/API/parameters/ConnectPolicyToNetSuiteParams.ts:1-6 — only policyID, netSuiteAccountID, netSuiteTokenID, netSuiteTokenSecret.
• Since the App is a pure credential pass-through and does not perform or validate the NetSuite role/permission check, no App-side change can fix a role permission error. The error text the tester sees is surfaced from the backend connection response.

Alternative explanations considered: A genuinely invalid/expired token or a NetSuite role missing TBA permissions would produce the same user-facing "role permission" error — these are far more likely than an Expensify role-name change, which the App never transmits.

---

Next Steps for Contributor+ team:
To accept: This requires a backend investigation outside the App repo — please escalate to an internal engineer with access to the NetSuite integration and connection logs.
To refine: @MelvinBot <your feedback>
To reject: Explain why you are rejecting Melvin's analysis.

[lorretheboy]

Proposal

What is the root cause of that problem?

The token-based connection itself only collects and sends the Account ID, Token ID and Token Secret — no Expensify role is ever transmitted, so the reporter's "Workspace admin vs Admin" theory isn't the mechanism:

App/src/libs/API/parameters/ConnectPolicyToNetSuiteParams.ts

Lines 1 to 6 in 6ca714a

	type ConnectPolicyToNetSuiteParams = {
	policyID: string;
	netSuiteAccountID: string;
	netSuiteTokenID: string;
	netSuiteTokenSecret: string;
	};

The "role permission error" is returned by NetSuite because of which NetSuite role the access token is attached to. Our setup instructions tell the user to attach the token to the "Expensify Integration" or "Administrator" role:

App/src/languages/en.ts

Lines 5362 to 5366 in 6ca714a

	createAccessToken: {
	title: 'Create an access token',
	description:
	'In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and either the "Expensify Integration" or "Administrator" role.\n\n*Important:* Make sure you save the *Token ID* and *Token Secret* from this step. You\'ll need it for the next step.',
	},

NetSuite does not allow the Administrator role to be used with token-based authentication (it is a 2FA-protected role excluded from TBA). So a user who follows the instruction and picks "Administrator" creates a token NetSuite refuses → ConnectPolicyToNetSuite runs with that token → NetSuite rejects it with a role permission error → connection fails. The instruction offering "Administrator" is the wrong guidance.

What changes do you think we should make in order to solve the problem?

Update the createAccessToken step so it only recommends the "Expensify Integration" role and drops the "Administrator" alternative:

App/src/languages/en.ts

Lines 5362 to 5366 in 6ca714a

	createAccessToken: {
	title: 'Create an access token',
	description:
	'In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and either the "Expensify Integration" or "Administrator" role.\n\n*Important:* Make sure you save the *Token ID* and *Token Secret* from this step. You\'ll need it for the next step.',
	},

i.e. change the description to ...create an access token for the "Expensify" app and the "Expensify Integration" role. Mirror the same wording change in the other locale files that carry this string (es.ts, fr.ts, de.ts, it.ts, nl.ts, pl.ts, pt-BR.ts, ja.ts, zh-hans.ts) so the guidance is consistent everywhere.

What alternative solutions did you explore? (Optional)

Keep both roles but add a note that "Administrator" cannot be used with token-based authentication and the "Expensify Integration" role (installed by the bundle) must be selected. This is more informative but wordier; simply removing the broken option is cleaner.

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @eh2077 (External)

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022071302868806242255

[godzillaxbox19982014-lgtm]

Proposal

Please re-state the problem that we are trying to solve in this issue.

NetSuite - Can't connect to NetSuite: role permission error

What is the root cause of that problem?

I traced this to the path that handles NetSuite:

• src/pages/workspace/accounting/netsuite/utils.ts:80 (hasAuthError): const hasAuthError = isAuthenticationError(policy, CONST.POLICY.CONNECTIONS.NAME.NETSUITE);
• src/pages/workspace/accounting/netsuite/NetSuiteTokenInput/NetSuiteTokenInputPage.tsx:32 (hasAuthError): const hasAuthError = isAuthenticationError(policy, CONST.POLICY.CONNECTIONS.NAME.NETSUITE);
• src/pages/workspace/accounting/netsuite/NetSuiteTokenInput/NetSuiteTokenInputPage.tsx:52 (shouldPageBeBlocked): const shouldPageBeBlocked = !isEmptyObject(policy?.connections?.[CONST.POLICY.CONNECTIONS.NAME.NETSUITE]) && !hasAuthError;
• The local evidence matches this recurring failure shape: NewDot and OldDot read different default account/card fields. Here, src/pages/workspace/accounting/netsuite/utils.ts:80 and src/pages/workspace/accounting/netsuite/NetSuiteTokenInput/NetSuiteTokenInputPage.tsx:32 do not agree on the same NetSuite value, so the user-visible path can show a missing or stale state even though nearby data already has the needed context.

What changes do you think we should make in order to solve the problem?

• Update src/pages/workspace/accounting/netsuite/utils.ts:80 to derive NetSuite from the card/accounting data source that owns this flow before the value is consumed.
• Carry the same normalized value through src/pages/workspace/accounting/netsuite/NetSuiteTokenInput/NetSuiteTokenInputPage.tsx:32; that follows the safer family move to add fallback at the export/mapping layer, so the write/optimistic/read paths agree instead of only changing the visible component.
• Keep the change inside the Payments, Wallet, Bank, Billing, Cards surface and avoid changing money movement, bank/card/account settings.

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

1. Add or update a regression in tests/unit/Payment*.ts for the exact issue flow: NetSuite - Can't connect to NetSuite: role permission error.
2. Cover the counter-case near src/pages/workspace/accounting/netsuite/utils.ts:80 so valid existing NetSuite behavior still works.
3. Manually repeat the issue steps after the patch and confirm the visible state/action is no longer stale.

What alternative solutions did you explore? (Optional)

• I would not add a broad new condition outside these referenced paths; the safer fix is to keep NetSuite consistent at the first read/write boundary shown above.

[neerajbachani]

Proposal

Please re-state the problem that we are trying to solve in this issue.

Users/testers can fail to connect NetSuite with a role permission error during the token-based NetSuite setup flow.

The failure is seen after entering the NetSuite Account ID, Token ID, and Token Secret. The reported guess is that this may be related to the Expensify role label changing from Admin to Workspace Admin, but that is not the actual App-side mechanism.

What is the root cause of that problem?

The NetSuite connect request does not send any Expensify role name or role label, so the Workspace Admin rename is not the cause.

The App sends only these fields when connecting NetSuite:

src/libs/API/parameters/ConnectPolicyToNetSuiteParams.ts

type ConnectPolicyToNetSuiteParams = {
    policyID: string;
    netSuiteAccountID: string;
    netSuiteTokenID: string;
    netSuiteTokenSecret: string;
};

That payload is built in src/libs/actions/connections/NetSuiteCommands.ts:

const parameters: ConnectPolicyToNetSuiteParams = {
    policyID,
    ...credentials,
};
API.write(command, parameters, {optimisticData});

So no Expensify workspace role, translated role name, Admin, or Workspace Admin value is sent to NetSuite.

The actual App-side issue is in the NetSuite setup instructions. The in-app wizard currently tells users they can create a NetSuite access token with either the Expensify Integration role or the Administrator role:

src/languages/en.ts

'In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and either the "Expensify Integration" or "Administrator" role...'

That guidance conflicts with Expensify’s own NetSuite setup and troubleshooting docs, which consistently say the token must be tied to the Expensify Integration role.

For example, docs/articles/new-expensify/connections/netsuite/Connect-To-NetSuite.md says:

Select **Expensify** as the application and the **Expensify Integration** role

And the role-permission troubleshooting docs say the same thing. Example from NS0565-Sync-Error.md:

Confirm the **Role** listed is **Expensify Integration**.

NetSuite access tokens are tied to a specific user-role combination. If the tester follows the App wizard and creates/uses a token under a role that is not the expected Expensify Integration role, the backend/NetSuite handshake can fail with a role permission error.

So the root cause is misleading in-app NetSuite setup copy: the App presents Administrator as a valid token role for this Expensify integration flow, while the supported setup requires the Expensify Integration role.

What changes do you think we should make in order to solve the problem?

Update the NetSuite token setup copy so it only instructs users to use the Expensify Integration role.

In src/languages/en.ts, change the createAccessToken.description copy from:

'In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and either the "Expensify Integration" or "Administrator" role.\n\n*Important:* Make sure you save the *Token ID* and *Token Secret* from this step. You\'ll need it for the next step.'

to wording like:

'In NetSuite, make sure the employee creating the token has the "Expensify Integration" role assigned. Then go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and the "Expensify Integration" role.\n\n*Important:* Make sure you save the *Token ID* and *Token Secret* from this step. You\'ll need it for the next step.'

This does two things:

1. Removes the incorrect Administrator alternative.
2. Adds the missing setup requirement that the token user must have the Expensify Integration role assigned.

Also update the same string in the localized language files that currently contain the same Expensify Integration / Administrator guidance: src/languages

I would not change the NetSuite connect API payload. It is already correct because the role is not selected in the App or sent by the App; the role is part of the NetSuite access token configuration.

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

This is primarily a copy/setup-guidance fix, so a full behavioral integration test is not necessary.

A lightweight regression check would be enough:

1. Add/update a test or snapshot around the NetSuite setup copy to ensure the access-token step no longer recommends Administrator.
2. Verify the access-token setup instruction still mentions Expensify Integration.
3. Keep the existing NetSuite command tests unchanged, since they correctly verify that connectPolicyToNetSuite sends only policyID, netSuiteAccountID, netSuiteTokenID, and netSuiteTokenSecret.

What alternative solutions did you explore? (Optional)

I considered the reporter’s Workspace Admin theory, but rejected it. The rename is display-only in the App. The underlying role constant is still admin, and the NetSuite connect request never sends any workspace role or translated role label.

[dilshodmackbook-sketch]

🚨 Edited by proposal-police: This proposal was edited at 2026-06-28 18:49:48 UTC.

Proposal

Please re-state the problem that we are trying to solve in this issue.

NetSuite – "Can't connect to NetSuite: role permission error" when creating a token-based connection.

What is the root cause of that problem?

The "Workspace Admin" vs "Admin" rename the tester noticed is a red herring. That string is only a UI display label (roleName in en.ts); CONST.POLICY.ROLE.ADMIN still resolves to admin, and the connect request never carries any Expensify role at all — its entire surface is four credential fields:

App/src/libs/API/parameters/ConnectPolicyToNetSuiteParams.ts

Lines 1 to 6 in 62df01f

	type ConnectPolicyToNetSuiteParams = {
	policyID: string;
	netSuiteAccountID: string;
	netSuiteTokenID: string;
	netSuiteTokenSecret: string;
	};

The "role permission error" comes from NetSuite, and it refers to the NetSuite role attached to the Access Token used for token-based authentication. Our in-app setup wizard tells the user to create that token for either the "Expensify Integration" or the "Administrator" role:

App/src/languages/en.ts

Lines 5362 to 5366 in 62df01f

	createAccessToken: {
	title: 'Create an access token',
	description:
	'In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and either the "Expensify Integration" or "Administrator" role.\n\n*Important:* Make sure you save the *Token ID* and *Token Secret* from this step. You\'ll need it for the next step.',
	},

That guidance is the defect. Expensify's own troubleshooting requires the Access Token to be tied to the Expensify Integration role specifically — a token created under "Administrator" is not recognized by the Expensify Integration and NetSuite rejects the connection with a role permission error:

App/docs/articles/new-expensify/connections/netsuite/Troubleshooting/Connection-errors/NS0565-Sync-Error.md

Lines 35 to 65 in 62df01f

	## How to Fix the NS0565 Sync Error
	Follow the steps below to confirm the correct role and permissions are configured.
	---
	## Confirm the Role Assigned to the NetSuite Access Token
	1. Log in to NetSuite as an administrator.
	2. Search for **Access Tokens**.
	3. Locate the token used for the Expensify connection.
	4. Click **View** next to the listed token.
	5. Confirm that the **Expensify Integration role** is assigned to the token.
	If the Expensify Integration role is already assigned, continue to the next section.
	---
	## Assign the Expensify Integration Role to the Employee Record
	If the Expensify Integration role is not assigned:
	1. Search for the NetSuite employee record used to create the access token.
	2. Click **Edit**.
	3. Select the **Access** tab.
	4. Add the **Expensify Integration role**.
	5. Click **Save**.
	After updating the employee record, confirm the access token is linked to the correct role.
	---

So a tester who follows the instruction and picks "Administrator" produces a token NetSuite refuses → connect fails. The instruction offering "Administrator" contradicts the documented requirement.

What changes do you think we should make in order to solve the problem?

Update the createAccessToken step so it recommends only the "Expensify Integration" role and drops the "Administrator" option, aligning the wizard with NS0565:

In NetSuite, go to *Setup > Users/Roles > Access Tokens* > create an access token for the "Expensify" app and the "Expensify Integration" role.

Mirror the same wording change in the other locale files that carry this string (es.ts, fr.ts, de.ts, it.ts, nl.ts, pl.ts, pt-BR.ts, ja.ts, zh-hans.ts) so the guidance is consistent everywhere.

Optionally (separate, non-blocking improvement): surface NetSuite's specific failure reason in the connection error state instead of the generic "Connection failed" copy, so the next tester sees "role permission" directly rather than guessing.

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

1. Snapshot/translation test asserting the createAccessToken description references the "Expensify Integration" role and no longer offers "Administrator", across all locale files.
2. Verify the connect flow still posts only the four credential fields (no role), guarding against accidental coupling of the UI role label into the NetSuite payload.

What alternative solutions did you explore? (Optional)

Keep both roles but add a note that "Administrator" cannot be used with the Expensify Integration token and the "Expensify Integration" role (installed by the bundle) must be selected. This is more informative but wordier; removing the broken option is cleaner and matches the docs.