Skip to main content

​
Overview

The NetSuite integration connects your agents to your NetSuite account over SuiteTalk REST using Token-Based Authentication (TBA / OAuth 1.0a). Agents can run SuiteQL reporting queries (joins, aggregates, GL detail) and read records through the REST record API — customers, invoices, sales orders, vendors, the chart of accounts, and any other record the connected role can see. With the gated write tool enabled, agents can also create, update, and delete records. Whether a given agent can write is a per-agent tool-selection decision — attach only the read tools for a read-only deployment. The role you connect is the real permission boundary: a View-only role simply cannot write, no matter which tools are attached.
Multi-instance. One Aster organization can hold several NetSuite accounts (e.g. two subsidiaries on separate instances). Connect each one under its own label; tools accept an optional instance parameter and default to the org’s default instance when omitted.

​
Prerequisites

  • A NetSuite account with the REST Web Services, Token-Based Authentication, and SuiteAnalytics Workbook features enabled
  • A NetSuite admin to create the integration record, role, and token (steps below)
  • An Aster admin to connect the integration (the connection is shared org-wide)

​
Setup Guide

The one-time NetSuite-side setup is what makes or breaks the connection. Follow the steps in order — in particular, create the access token last, after the role’s permissions are final.
1

Enable the required features (NetSuite admin)

Setup → Company → Enable Features:
  • SuiteCloud subtab → check REST Web Services and Token-Based Authentication.
  • Analytics subtab → check SuiteAnalytics Workbook.
SuiteAnalytics Workbook is not optional. Its permission gates the entire REST API for a custom role — not just SuiteQL. Without it, every SuiteQL query and every REST record call returns 400 — Your current role does not have permission to perform this action, even when REST Web Services is already granted. The permission also won’t appear in the role editor until this feature is enabled.
2

Create an integration record (NetSuite admin)

Setup → Integration → Manage Integrations → New. Name it (e.g. “Aster Agents Integration”), check Token-Based Authentication, and leave the OAuth 2.0 boxes unchecked. On save, NetSuite shows the Consumer Key and Consumer Secret once — copy them now; they cannot be retrieved later.
3

Create a dedicated role (NetSuite admin)

Setup → Users/Roles → Manage Roles → New. Grant these permissions:On OneWorld accounts, set Subsidiary Restrictions → All (or all subsidiaries the agent must see). A single-subsidiary role silently returns partial data with no error. Assign the role to a dedicated integration user (Setup → Users/Roles → Manage Users).
4

Create an access token — LAST (NetSuite admin)

Setup → Users/Roles → Access Tokens → New. Select the integration, the user, and the role, then save. NetSuite shows the Token ID and Token Secret once — copy them now.
Mint the token after the role’s permissions are final. A token created before you finish granting permissions may not pick up later changes — you’ll keep seeing “does not have permission” until you issue a fresh token. If in doubt, delete the token and create a new one.
5

Find your Account ID (NetSuite admin)

Setup → Company → Company Information → Account ID (e.g. 1234567, or 1234567_SB1 for a sandbox). Send Aster the five values over a secure channel (never email): Account ID, Consumer Key, Consumer Secret, Token ID, Token Secret.
6

Connect NetSuite in Aster Agents (Aster admin)

Navigate to Control Hub → Integrations, locate the NetSuite card, click Connect, give the instance a label, and enter the five values. Aster validates them live (a benign SuiteQL call) and confirms the connection. To add a second NetSuite account, connect again with a different label.
7

Add tools to your agent (Aster admin)

Edit your agent and enable the NetSuite tools it needs — NetSuite Query for reporting, plus Get Record / List Records for record reads, and Manage Records only if the agent should write.

​
Available Tools

  • NetSuite Query (netsuite_query) — Runs a SuiteQL SELECT (joins, aggregates, filters) — the primary reporting/KPI workhorse. Read-only by construction; non-SELECT statements are rejected. Auto-paginates up to a row cap and spills large result sets to a CSV attachment while truncating the inline payload to a token budget.
  • NetSuite Get Record (netsuite_get_record) — Fetches a single record by type and internal id, optionally expanding sub-resources.
  • NetSuite List Records (netsuite_list_records) — Lists/filters a record type via the REST record API, with paging and an optional q filter.
  • NetSuite Manage Records (netsuite_manage_records) — Gated write. Creates, updates, or deletes records. Attach only to agents that should write; a View-only role safely rejects writes with a 403.
SuiteQL is the reliable way to filter. For anything beyond a simple list, prefer netsuite_query with a WHERE clause — it’s more expressive (joins, aggregates) and avoids the encoding quirks of REST query-string filters.

​
Example Prompts

Once connected, agents can answer questions like:
  • “What was total revenue by month for the last quarter, from the GL?” (SuiteQL aggregate)
  • “Pull all open invoices over $10,000 with their due dates.” (the full set spills to a CSV the agent can process in Python)
  • “Show me sales order SO12345 and its line items.”
  • “Which vendors did we add this year?”
  • (with the write tool) “Create a customer record for Acme Corp in the East subsidiary.”

​
Notes & Limitations

  • Full CRUD, gated by role and tools — reads and writes are both supported; the connected role’s permissions and the tools you attach determine what an agent can actually do.
  • Permissions follow the connected role — agents only see records the integration role can see. Scope that role to least privilege.
  • SuiteQL page size — NetSuite caps SuiteQL at 1,000 rows per page; the tool auto-paginates to reach larger totals and spills big pulls to CSV.
  • OneWorld — set the role’s Subsidiary Restrictions to All (or every relevant subsidiary), or reads silently return partial data.
  • Account-wide concurrency — NetSuite rate limits (429) are shared across all of the account’s integrations, tier-dependent. Prefer narrow filters over bulk pulls.
  • Sandbox vs. production — the REST host is derived from the Account ID (1234567_SB1 → 1234567-sb1.suitetalk.api.netsuite.com); a sandbox refresh may require re-issuing credentials.

​
Security Considerations

  • Org-level connection — one admin connects once for the whole organization. The Consumer Secret and Token Secret are stored server-side and redacted when the connection is read back in the UI.
  • The role is the boundary — deploy read-only by connecting a View-only role and not attaching the write tool; a read-only role rejects any write with a 403.
  • Use a dedicated integration user and role with least privilege, so access can be audited and revoked independently of any person.
  • Grant the NetSuite tools only to agents that need them, and the write tool only where writes are intended.

​
Troubleshooting

  • The token authenticated (you got a 400, not a 401), but the role lacks access. The usual culprit is the missing SuiteAnalytics Workbook permission (Reports subtab) — it gates all REST, not just SuiteQL — and its feature must be enabled first.
  • Confirm the role also has REST Web Services and Log in using Access Tokens, plus a View permission on each record type queried.
  • If you added permissions after creating the token, issue a new token — an existing token may not pick up the new permissions.
  • A 401 is a signature/credential problem. Re-check all five values for stray spaces, and confirm the Account ID matches Company Information exactly (including any _SB1 sandbox suffix).
  • NetSuite occasionally returns a transient 401 on an otherwise-valid request, especially in the first minutes after a token is created — retry.
  • On OneWorld, the role’s Subsidiary Restrictions are probably not set to All — a subsidiary-scoped role returns partial data with no error.
  • Run Code — process large NetSuite result sets (the CSV spillover attachment) with pandas.