---
title: "Oracle NetSuite custom role for Administrators - Payhawk Help Center"
slug: "authenticating-to-oracle-netsuite-with-a-custom-role"
description: "See the minimum Oracle NetSuite permissions a custom role needs for the Payhawk SuiteApp, how to create and assign the role, and how to fix permission errors."
updated: 2026-10-20T07:44:38Z
published: 2026-10-20T07:44:38Z
canonical: "payhawk.com/authenticating-to-oracle-netsuite-with-a-custom-role"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://payhawk.com/help/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating to Oracle NetSuite with a custom role

This article lists the minimum NetSuite permissions required for a custom role to use the Payhawk SuiteApp RESTlets. The SuiteApp no longer requires the Administrator role — any role with Token-Based Authentication (TBA) access and the permissions listed below can be used.

## Reference documentation

- [Permissions Documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N326485.html) — overview + downloadable [NetSuitePermissionsUsage.xls](https://system.netsuite.com/core/media/media.nl?id=457595427&c=NLCORP&h=ka92WVqy8jC7TwBWowHI-TQdnY1wrOwpnd4ogvcz1V6MeRID&_xt=.xls)
- [Permission Names and IDs](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_N3236764.html) — complete ID table for SuiteScript
- [Roles and Permission Considerations for APIs](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0320025211.html) — API-specific requirements
- [Access Levels for Permissions](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N326341.html) — None / View / Create / Edit / Full definitions
- [Customizing or Creating NetSuite Roles](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N285937.html) — step-by-step guide

## Creating a custom role

To create a dedicated role for the Payhawk integration, follow the steps:

1. In Oracle NetSuite, go to `Setup -> Users/Roles -> Manage Roles -> New` .
2. Name the role, for example, **Payhawk Integration**.
3. On the role record, check **Web Services Only Role** (recommended - prevents UI login with this role).
4. Add the permissions listed below under the Permissions subtabs (Setup, Transactions, Lists).
5. Save the role.
6. Assign the role to the user: `Lists -> Employees -> [User] -> Access -> Roles`.

## Permissions

### Transactions

**Role** page → **Permissions** → **Transactions** subtab

| Permission | Level |
| --- | --- |
| Bills | Full |
| Deposit | Create |
| Enter Vendor Credits | Full |
| Expense Report | Full |
| Find Transaction | View |
| Make Journal Entry | Full |
| Pay Bills | Full |
| Purchase Order | Full |

### Reports

**Role** page → **Permissions** → **Reports** subtab

| Permission | Level |
| --- | --- |
| Cash Flow Statement | View |

### Lists

**Role** page → **Permissions** → **Lists** subtab

| Permission | Level |
| --- | --- |
| Accounts | Full |
| Amortization Schedules | View |
| Classes | View |
| Currency | Full |
| Custom GL lines Plug-in Audit Log | View |
| Customers | View |
| Departments | View |
| Documents and Files | Full |
| Employee Record | Full |
| Employees | Full |
| Items | View |
| Locations | View |
| Projects | View |
| Subsidiaries | View |
| Tax Records | View |
| Vendors | Full |

### Setup

**Role** page → **Permissions** → **Setup** subtab

| Permission | Level |
| --- | --- |
| Accounting Preferences | Full |
| Company Information | Full |
| Custom Body Fields | View |
| Custom Column Fields | View |
| Custom Entity Fields | View |
| Custom Fields | View |
| Custom Item Fields | View |
| Custom Lists | View |
| Custom Record Types | View |
| Custom Segments | View |
| Custom Transaction Fields | View |
| Custom Transaction Forms | View |
| Log in using Access Tokens | Full |
| Manage Accounting Periods | View |
| Manage Tax Reporting Periods | Full |
| Other Custom Fields | View |
| SuiteScript | View |

![Permissions settings for Transactions, Reports, Lists, Setup, and Custom Record options.](https://storage.googleapis.com/payhawk-cdn/Adm%3AIntegrations%3ANetSuite/authenticating_1.png)

### User global permissions

| Permission | Level |
| --- | --- |
| Access Token Management | Full |
| Entity-Subsidiary Relationship | Full |
| SuiteSignOn | Full |

![The interface displays Global Permissions and various access levels for user roles.](https://storage.googleapis.com/payhawk-cdn/Adm%3AIntegrations%3ANetSuite/authenticating_2.png)

## Notes for developers

> [!WARNING]
> **Generic endpoints**: The `records-restlet` and `suiteql-restlet` are generic endpoints that can access any record type. The role must have permissions for every record type queried through them. If a permission is missing, these endpoints will return a structured error.

- **Backward compatibility:** The SuiteApp continues to work with the Administrator role. No changes are required for existing connections using Admin.
- **Full permissions reference:** For a complete understanding of all NetSuite permission implications, download the official [NetSuitePermissionsUsage.xls](https://system.netsuite.com/core/media/media.nl?id=457595427&c=NLCORP&h=ka92WVqy8jC7TwBWowHI-TQdnY1wrOwpnd4ogvcz1V6MeRID&_xt=.xls).

## Troubleshooting

**Diagnostic**: Check the Login Audit Trail at `Setup -> Users/Roles -> View Login Audit Trail`. Add the *Detail*, *Token-based Access Token Name*, and *Token-based Application Name* columns to see detailed failure reasons.

**INSUFFICIENT_PERMISSION / insufficient-permissions**

This error means TBA authentication succeeded but the role lacks permissions for the specific record or operation. The `records-restlet` and `suiteql-restlet` return a structured error:

```plaintext
{ "errors": [{ "code": "insufficient-permissions", "message": "..." }] }
```

Add the missing permission from the tables above. The error message typically names the record type that requires access.

**Permission_denied**

This TBA-level error means the role or user entity is not usable. Verify:

1. The role is active (not disabled).
2. The user has not made the role inactive on their **View My Roles** page.
3. The role has TBA permissions assigned.