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

# NetSuite Integration

> Connect HelloLeo to your NetSuite account

<video controls playsInline src="https://cdn.helloleo.dev/tutorials/netsuite-connection-full-demo.mp4" />

Connect HelloLeo to your NetSuite account so Leo can read your schema during
development and the app it builds can sign users in with their own NetSuite
account.

The connection happens in a guided 4-step wizard: **Account ID → MCP record →
Runtime record → All set**. Open it by clicking the NetSuite logo in the chat
input on your home page, or from your project's **Integrations** panel.

Plan \~15 minutes the first time. You'll need NetSuite Administrator access
**once** for the initial setup. After that, day-to-day use happens through a
dedicated non-admin role — and reconnecting NetSuite on your next project
takes under a minute with a saved connection.

## Before you start (one time, in NetSuite)

### Enable the required features

`Setup → Company → Enable Features → SuiteCloud`. Check ALL of:

* Client SuiteScript
* Server SuiteScript
* OAuth 2.0
* REST Web Services

Save. Accept the SuiteCloud Terms if prompted.

### Install the MCP SuiteApp

`Customization → SuiteBundler → Search & Install Bundles → "MCP Standard
Tools"`. Install. This SuiteApp is what lets Leo introspect your schema —
without it, Leo can't see your records.

### Create a non-admin role + user

> **Important.** Do not connect HelloLeo with your Administrator account.
> NetSuite blocks OAuth 2.0 for Administrator for security reasons. Even if
> you find a workaround, you should never connect a third-party app with
> Administrator — least privilege limits damage if a token leaks.

The wizard links to this guide from its **"Open role setup guide"** button.

**The role.** `Setup → Users/Roles → Manage Roles → New`. Name it
`HelloLeo Integration`. Under **Access → Global Authorizations**, set these
three to **Unlimited**:

| Authorization                        | Level     | What it unlocks                                                                                                                                |
| ------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP Server Connection                | Unlimited | Lets Leo connect to the MCP server.                                                                                                            |
| Log in using OAuth 2.0 Access Tokens | Unlimited | Allows OAuth 2.0 authentication (this is the OAuth 2.0 permission — **not** the older "Log in using Access Tokens" used for token-based auth). |
| REST Web Services                    | Unlimited | Allows REST API access from the app Leo builds.                                                                                                |

Under **Permissions** on the role, add read/write on the record types your
app will touch (Customers, Sales Orders, Items, etc.). Save.

**The user.** `Setup → Users/Roles → Manage Users`. Create a new user (e.g.
`helloleo@yourcompany.com`) or open an existing non-admin user, and assign the
`HelloLeo Integration` role. Then on the user record, under
**Access → Global Authorizations**, set the same three to **Unlimited**.

Save. The role grants and the user-level grants must both be present —
NetSuite intersects them and grants only what BOTH allow.

This is the user you'll sign in as when authorizing HelloLeo and when testing
the deployed app.

## Step 1 — Account ID

Paste your Account ID (`1234567`, or `1234567_SB1` for sandboxes) — or simply
paste any NetSuite URL and the wizard extracts it for you. You can find it in
`Setup → Company → Company Information`.

The wizard shows the API host it resolved so you can sanity-check it, then
click **Continue**.

## Step 2 — MCP record (Leo reads your schema)

In most cases **HelloLeo creates this Integration Record for you**: NetSuite
auto-installs it when you authorize. You don't create anything and there's no
Consumer Key to copy — just click **Connect with NetSuite**, sign in with your
`HelloLeo Integration` user (NOT Administrator) in the NetSuite window that
opens, pick the role, and approve.

Once authorized, the wizard shows **"MCP connected — Leo can introspect your
schema"** and moves on.

### Manual fallback

If you prefer creating the record yourself (or auto-install fails), expand
**"Prefer to create the record yourself, or auto-install failed?"** in the
wizard. It shows the exact settings with copy buttons, which map to
`Setup → Integration → Manage Integrations → New`:

| Field                      | Value                                                                          |
| -------------------------- | ------------------------------------------------------------------------------ |
| Name                       | `HelloLeo MCP`                                                                 |
| State                      | Enabled                                                                        |
| Token-Based Authentication | leave **unchecked**                                                            |
| Authorization Code Grant   | **Checked**                                                                    |
| Public Client (PKCE)       | **Checked**                                                                    |
| Redirect URI               | copy it from the wizard                                                        |
| Scope                      | **NetSuite AI Connector Service** only — leave ALL other scope boxes unchecked |

Save. NetSuite shows the **Consumer Key** and **Consumer Secret** once — paste
them into the wizard, then click **Connect with NetSuite** and authorize as
above.

## Step 3 — Runtime record (your app signs users in)

The app Leo builds signs your users in against a **second** Integration
Record, separate from the MCP one. NetSuite refuses to mix scopes on one
record, which is why there are two:

|         | Record 1 — MCP                                      | Record 2 — Runtime                               |
| ------- | --------------------------------------------------- | ------------------------------------------------ |
| Scope   | NetSuite AI Connector Service                       | REST Web Services                                |
| Used by | HelloLeo (Leo reads your schema during development) | The app Leo builds (your end-users sign in here) |

When you reach this step, HelloLeo first provisions your app's environment
automatically ("Setting up your app's environment…") — this produces the exact
**Redirect URI** your record needs, no guessing.

Then create the record in `Setup → Integration → Manage Integrations → New`
(the wizard's **"Show me how"** banner has every value with a copy button):

| Field                      | Value                                                                     |
| -------------------------- | ------------------------------------------------------------------------- |
| Name                       | `HelloLeo Runtime`                                                        |
| State                      | Enabled                                                                   |
| Token-Based Authentication | leave **unchecked**                                                       |
| Authorization Code Grant   | **Checked**                                                               |
| Public Client (PKCE)       | **Checked**                                                               |
| Redirect URI               | copy the exact value from the wizard. `https://` only, no trailing slash. |
| Scope                      | **REST Web Services** only — leave ALL other scope boxes unchecked        |

Save, copy the Consumer Key + Consumer Secret, and paste them into the wizard.
They're stored as HelloLeo Cloud secrets — never sent back to the browser.

> **Reusing one record across projects.** NetSuite lets a single Integration
> Record hold **multiple** Redirect URIs. Instead of a new record per HelloLeo
> project, you can reuse this one: add each project's Redirect URI to the same
> record and paste the same Consumer Key/Secret into each project.

## Step 4 — All set

The wizard confirms **"Your NetSuite connection is active"**. Leo can read
your schema, and your app can sign users in. Start building.

To verify end-to-end: open your deployed app, click **Sign in with
NetSuite**, and authorize with your `HelloLeo Integration` user. You should
land back in the app, signed in, with real data loading.

## Reusing your connection on the next project

Authorizing NetSuite automatically saves the connection (Account ID +
credentials) to your account. On your next project, the wizard opens with a
choice:

* **Use a saved connection** — pick it from the list; the wizard loads its
  Account ID and Consumer Key and jumps straight to the authorize step. You
  still click **Connect with NetSuite** once to authorize this project, and
  the Runtime step configures itself hands-free.
* **Create a new one** — the full flow above, for connecting a different
  NetSuite account.

## Reconnecting or disconnecting

Open the wizard on a connected project and you'll find **Reconnect / edit**
(restarts the wizard with your values pre-filled — useful if NetSuite revoked
a token or you rotated a Consumer Secret) and **Disconnect** at the bottom.

## Who signs in where

| Action                                               | Account / role                                                                      |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Initial NetSuite setup (features, SuiteApp, records) | Administrator (one-time only).                                                      |
| Authorizing in the wizard (Step 2)                   | Your `HelloLeo Integration` user (NOT Administrator).                               |
| End-users signing into the deployed app              | Their own NetSuite user, with a role that has the same three Global Authorizations. |

For end-users that aren't yet in NetSuite, your Administrator creates each
user and assigns the role — same pattern as above.

## Troubleshooting

* **`INVALID_REDIRECT_URI`** — The Redirect URI on your record doesn't exactly
  match what the wizard gave you. Use the wizard's copy button. No trailing slash.
* **`scope_mismatch`** — You checked more than one scope on a single
  Integration Record. Each record must have exactly one scope.
* **NetSuite refuses to authorize as Administrator** — Expected. Switch to
  the `HelloLeo Integration` user. NetSuite blocks OAuth 2.0 for Administrator.
* **`USER_PERMISSION_VIOLATION` after sign-in** — Your role is missing one
  of the three Global Authorizations (MCP Server Connection /
  Log in using OAuth 2.0 Access Tokens / REST Web Services). Re-check both the
  role AND the user record, save, retry.
* **Leo can't see your schema** — The "MCP Standard Tools" SuiteApp isn't
  installed. See "Before you start".
* **Auto-install fails on Step 2** — Use the manual fallback: expand
  "Prefer to create the record yourself", create the `HelloLeo MCP` record
  with the settings shown, and paste its Consumer Key/Secret.
* **"Connect" button disabled in HelloLeo** — Refresh the HelloLeo page and
  try again.