Connecting Acumatica to Cube

This article walks your Acumatica administrator through everything Cube needs to connect to your Acumatica instance: creating an API user, choosing an authentication method, setting up a web service endpoint, and sharing credentials securely. Your Cube Implementation Manager and Integration Engineer will work through the connectivity steps with you live, so treat this as a preparation guide and reference.

Overview

Cube connects to Acumatica through Acumatica's contract-based REST API. Cube's integration platform authenticates to your instance, calls a web service endpoint you create for Cube, and pulls your general ledger activity (typically journal transactions or a summarized inquiry) on a scheduled basis. The connection is read-only: Cube never writes data back to Acumatica.

To get connected, you will need someone with administrator access to your Acumatica instance who can create users, manage connected applications, and create web service endpoints. Plan for one or two working sessions with the Cube team to establish and test the connection.

What Cube needs from you

Step 1: Create an API user for Cube

1. In Acumatica, create a new user dedicated to the Cube integration. Your Cube team will provide the email address to use for this user.
2. Assign the user a role with API access (access to API data). Front-end UI permissions are not required; the user only needs to be able to log in via the API and read the financial screens and endpoints Cube will call.
3. Enable the option that allows the user's password to be reset, in case Cube needs to rotate the credential later.

Step 2: Choose an authentication method

Acumatica supports two authentication methods that work with Cube. Your Cube Integration Engineer will confirm which one to use on your connectivity call.

Option A: OAuth 2.0 (Connected Application)

This is Acumatica's recommended mechanism. You register Cube as a connected application and share a client ID and secret instead of a password.

1. Navigate to Integration > Connected Applications (screen SM303010).
2. Create a new application named Cube. Leave the Client ID blank; Acumatica generates it on save.
3. Select the OAuth 2.0 flow your Cube team requests (typically Client Credentials or Resource Owner Password).
4. On the Secrets tab, add a shared secret. Set the expiration as far out as your security policy allows, and copy the secret value immediately. It is only shown once.
5. Save, then share the generated Client ID and the secret with Cube through a secure channel (see Step 4).

Note: The fields available on the Connected Applications screen vary by Acumatica version. If your version does not expose the flow or scope options Cube needs, don't worry: basic session authentication (Option B) works reliably and is used by many Cube customers on Acumatica.

Option B: Basic session authentication (login/logout)

With this method, Cube logs in with the API user's credentials, receives a session cookie, makes its data calls, and logs out when finished.

• Login call: POST https://<your instance>/entity/auth/login with a JSON body containing the username, password, tenant, and branch.
• Logout call: POST https://<your instance>/entity/auth/logout after each session. Cube's integration always logs out to release the API session, so the connection will not hold licenses open or generate hanging sessions.

If you choose this option, you will share the API user's username and password with Cube through a secure channel (see Step 4).

Step 3: Create a web service endpoint for Cube

1. Navigate to Integration > Web Service Endpoints (screen SM207060).
2. Create a custom endpoint for Cube. The simplest approach is to extend or copy the Default endpoint and name it Cube. This gives Cube access to the standard entities (such as Journal Transactions) without any custom mapping work.
3. Note the endpoint name and version. The resulting base URL Cube will call looks like:
   https://<your instance>/entity/Cube/<version>/

Step 4: Share credentials securely

Never send passwords, client secrets, or API keys in a plain email. Your Cube team will send you a one-time secret link where you can submit the credentials. The link can only be opened once, and the contents are destroyed after they are viewed. Share these items through that link:

• Instance base URL and the Cube endpoint URL (including version)
• Tenant and branch names
• OAuth client ID and secret, or the API user's username and password

Step 5: Test connectivity with Cube

Your Cube Integration Engineer will schedule a working session to test the connection live. On that call, Cube will:

1. Authenticate against your instance and confirm a successful login.
2. Call the Cube endpoint (for example, the Journal Transactions entity) with date or period filters.
3. Validate a sample of the returned data with your finance team.

Having a sample payload or report export handy (for example, a trial balance or GL detail export for one period) helps Cube validate that the API data matches what your finance team expects to see.

What data does Cube pull?

For most Acumatica customers, Cube pulls journal transaction data with attributes such as: accounting date, financial period, module, batch number, account (number and description), account class, subaccount, branch, transaction type and description, reference number, and debit and credit amounts. Cube calculates the signed amount as debits minus credits.

These attributes map to your top-level dimensions in Cube (typically Account, Department via subaccount, and Entity via branch, alongside Scenario and Time). Your Implementation Manager will confirm the exact field mapping during your solution design.

Historical data

The API can only return data that exists in your Acumatica instance. If you migrated to Acumatica recently, transactions before your go-live date will not be available via the API. Cube handles earlier periods by loading opening balances or historical files directly, so you still get your full reporting history.

High transaction volumes: the Generic Inquiry option

If your business generates a very large number of GL transactions per month (for example, high-volume e-commerce), pulling every individual transaction through the API can be slow. In that case, Cube can instead connect to an Acumatica Generic Inquiry (GI) that pre-summarizes your GL activity while preserving the dimensions you report on.

Your Acumatica admin builds a GI that:

• Joins the GL transaction table with the subaccount table.
• Groups totals by account, subaccount, branch, ledger, and financial period.
• Includes total debit and total credit columns (Cube computes the net amount).

The GI is then made available to Cube either by checking Expose via OData on the inquiry, or by adding the GI to the Cube web service endpoint. This dramatically reduces data volume and refresh times while keeping department-level reporting intact. Your Cube team will guide you through this setup if it applies to you; a working session with your Acumatica admin is usually the fastest path.

FAQs

Does a version upgrade of Acumatica break the connection?
No. Acumatica version upgrades (for example, moving to a new R1/R2 release) preserve existing web service endpoints. The connection continues to work after upgrades.

Is the connection read-only?
Yes. Cube only reads data from Acumatica. The API user can be restricted to read permissions.

What if we get stuck?
Your Implementation Manager can pull in Cube's integration engineering team, and if the issue is on the Acumatica side, the public Acumatica Community forum is an excellent resource. Cube can also load your data manually from an Excel export at any point if you need numbers in Cube before a connection issue is resolved, so a connectivity hiccup never blocks your close.