# NetSuite

> Connect NetSuite to LightHouse: OAuth 2.0 client credentials (machine to machine) with your certificate, the scope it asks for, where the credential is held, and what is indexed.

The engine reads customers, transactions, items and support cases from your NetSuite account, by SuiteQL, into a knowledge base.

Content is read in place, in your deployment, in your own account. LightHouse receives ids, hashes and counts only. The records are not transmitted, and LightHouse does not open the credential.

## The way to connect

| Way                                        | What you do                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connect by OAuth 2.0 certificate (M2M)** | Make an integration record with the client-credentials grant, generate a certificate and upload it under **Setup → Integration → OAuth 2.0 Client Credentials (M2M) Setup**, mapped to a role that only views. Paste three lines: the client id, the certificate id NetSuite gave, then the PEM of the certificate’s private key. Never a password, and never a token-based-authentication secret pair |

## Connect in LightHouse

You need the **Client administrator** (`client_admin`) role, signed in as a person, and a deployment whose engine reads this connector ([compatibility reference](/concepts/telemetry-contract/#compatibility-reference)) and keeps credentials in your own store.

1. Go to **Setup and admin → Connectors**, find **NetSuite** (search for it, or filter by its family), and choose **Connect**.
2. Fill in `account_id` (such as `1234567`, or `1234567_SB1` for a sandbox) and `objects`.
3. The connection is **Read only**: this connector offers no other level.
4. Paste three lines: the client id, the certificate id, then the PEM of the private key. Your browser seals it to your deployment; LightHouse never sees it.
5. Your deployment keeps it and checks it at the provider. The card shows the result.

## Connect in code

```yaml
- id: netsuite-knowledge
  purpose: Read NetSuite into the knowledge base.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: ops-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: netsuite
    objects: [customers, transactions, items, cases]
    label: internal
    credential_secret: <connection id>
    requires:
      reads: [netsuite:customers, transactions, items and support cases]
      reason: the finance agents answer from the ledger and the case history
```

## Scope

- **Read only, always**: the `rest_webservices` scope, with a mapped role that has view permission on the records named and nothing that creates or edits. Read and write is not offered.
- **The health check**: your deployment signs a five-minute assertion with the key, gets an hour’s token and reads one customer id. NetSuite states the token’s scope, and the card shows it.
- **One host**: `<account>.suitetalk.api.netsuite.com`, made from the sealed account id.

## Where the credential is held

LightHouse never opens this credential. It is sealed in your browser, or by `lighthouse-ai connect netsuite --credential-stdin`, to your deployment’s own key, and your deployment keeps it in your own secrets store under `lighthouse/connectors/netsuite/<connection id>`. A request that sends it to LightHouse unsealed is refused with `422 sealing_required`. LightHouse keeps the connection’s fingerprint, the access level, the scopes the provider states and when it was checked: never the credential, and never what it reads.

See [Where every credential is held](/connect/#where-every-credential-is-held).

## What is indexed

- **Customers, transactions, items and support cases**: the business record’s columns. A customer’s email and phone are not read.
- **How often, and what is read each time**: on the card’s schedule. Each pull reads records whose `lastmodifieddate` is after the cursor. NetSuite gives that date in the account’s time zone with no offset, so the query starts a day before the cursor and anything not newer is dropped. A first pull past SuiteQL’s 100,000-row paging limit starts again from the newest time it read.
- **Deletions**: every six hours the ids are listed and a record that has gone is removed.
- **Rate limits**: NetSuite’s concurrency limits; requests are sequential and a `429` waits as long as NetSuite asks.
- **Never read**: records you do not name, files and saved searches.

## Check it worked

- The source’s run note in your deployment: `written N, unchanged N, quarantined N, removed N`.
- **Agents → Knowledge**: documents from `netsuite`.
- Content is read in place, in your deployment. LightHouse receives ids, hashes and counts only; the records are not transmitted.

## Removing it

On the card, choose **Disconnect**. Your deployment deletes the credential from your store. Revoke the certificate’s mapping in **OAuth 2.0 Client Credentials (M2M) Setup** in NetSuite. Documents already written stay in the corpus until you delete them.

Source: https://docs.atlanticagenticlabs.com/connect/netsuite/