> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Connect Token-Based Accounting Provider > Create or refresh an accounting connection for providers outside the browser OAuth flow — NetSuite (SuiteTalk token) and Tally (local export). Creates or refreshes an accounting connection for providers that do not use the browser OAuth flow of [Initiate Accounting OAuth](/api-reference/accounting/connect). `netsuite` takes a NetSuite account id and a SuiteTalk OAuth 2.0 access token minted in NetSuite's own UI (experimental). `tally` takes no credentials at all — connecting simply enables the local JSONL export sync that Tally's import tooling reads. If a row for the provider already exists — active, or inactive because [Disconnect Accounting Integration](/api-reference/accounting/disconnect) cleared `is_active` (the row is kept) or a sync deactivated it after the provider rejected its token — it is updated in place and reactivated with `sync_status` reset to `idle` and `last_error` cleared; otherwise a new one is created. The lookup does not filter on `is_active`, so any earlier connection for the provider is refreshed rather than duplicated. Trigger a push afterwards with [Trigger Accounting Sync](/api-reference/accounting/sync). ## Path Parameters | Parameter | Type | Required | Description | | ---------- | ------------- | -------- | --------------------- | | `provider` | string (path) | Yes | `netsuite` or `tally` | ## Body Parameters Optional for `tally`; required for `netsuite`. | Parameter | Type | Required | Description | | -------------- | ------ | -------------- | ----------------------------------------------------------------------- | | `account_id` | string | For `netsuite` | NetSuite account id; stored as the connection's `realm_id` | | `access_token` | string | For `netsuite` | SuiteTalk OAuth 2.0 access token; stored server-side and never returned | ## Example Request ```bash theme={null} curl -X POST "https://api.recurso.dev/v1/accounting/connect-token/netsuite" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "account_id": "1234567_SB1", "access_token": "eyJraWQiOiJjLjEyMzQ1NjciLCJhbGciOiJQUzI1NiJ9.example" }' ``` ## Response Returns `201 Created` for a new connection, or `200 OK` when an existing connection for the provider was refreshed. Tokens are never serialized; `token_expires_at`, `realm_id`, `last_sync_at`, and `last_error` are omitted while unset. The `AccountingConnection` schema the playground renders was written for the OAuth providers: it lists `provider` as `quickbooks`/`xero`, describes `realm_id` as a QuickBooks company or Xero organisation id, and types `token_expires_at`/`last_sync_at` as nullable. This endpoint returns `netsuite` or `tally`, stores the NetSuite account id in `realm_id`, and omits unset fields rather than sending `null` — the shape below is what the API actually sends. ```json theme={null} { "data": { "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "tenant_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b", "provider": "netsuite", "realm_id": "1234567_SB1", "sync_status": "idle", "is_active": true, "created_at": "2026-09-01T10:42:17Z" } } ``` ## Fields | Field | Type | Description | | ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------- | | `id` | string (uuid) | The connection's id — use it with [Disconnect Accounting Integration](/api-reference/accounting/disconnect) | | `tenant_id` | string (uuid) | The owning workspace | | `provider` | string | `netsuite` or `tally` | | `realm_id` | string | The NetSuite account id; omitted for `tally` | | `token_expires_at` | string (date-time) | Omitted — token-based connections carry no expiry | | `last_sync_at` | string (date-time) | When the last sync ran; omitted until the first sync | | `sync_status` | string | `idle` right after connecting | | `last_error` | string | Last sync error; omitted when clear | | `is_active` | boolean | `true` after connecting | | `created_at` | string (date-time) | When the connection was first created (unchanged on refresh) | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `400` | `validation_failed` | `provider` is not `netsuite` or `tally` (`provider does not support token-based connection`) | Use [Initiate Accounting OAuth](/api-reference/accounting/connect) for QuickBooks and Xero | | `400` | `validation_failed` | `provider` is `netsuite` and `account_id` or `access_token` is blank | Send both fields | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `500` | `internal_error` | The connection could not be saved | Retry; contact support if it persists | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml POST /v1/accounting/connect-token/{provider} openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/accounting/connect-token/{provider}: post: tags: - Accounting summary: Connect a token-based accounting provider (NetSuite, Tally) description: > Creates or refreshes a connection for providers outside the browser OAuth flow. `netsuite` requires `account_id` and a SuiteTalk OAuth 2.0 `access_token` minted in NetSuite (EXPERIMENTAL). `tally` takes no credentials — it enables the local JSONL export sync. operationId: connectAccountingProviderToken parameters: - name: provider in: path required: true schema: type: string enum: - netsuite - tally requestBody: required: false content: application/json: schema: type: object properties: account_id: type: string description: NetSuite account id (required for netsuite). access_token: type: string description: SuiteTalk OAuth 2.0 access token (required for netsuite). responses: '200': description: Existing connection refreshed. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AccountingConnection' '201': description: Connection created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AccountingConnection' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: AccountingConnection: type: object description: OAuth access/refresh tokens are stored server-side and never serialized. properties: id: type: string format: uuid tenant_id: type: string format: uuid provider: type: string enum: - quickbooks - xero token_expires_at: type: - string - 'null' format: date-time realm_id: type: string description: QuickBooks company ID / Xero organisation ID. last_sync_at: type: - string - 'null' format: date-time sync_status: type: string examples: - idle last_error: type: string is_active: type: boolean created_at: type: string format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````