Connecting an instance
What makes Acumatica different
There is no vendor-wide app to authorize. Every customer runs their own instance, and the OAuth client is registered inside that instance by someone with admin rights on it. So connecting is never a button you press alone — it needs five minutes from whoever administers the ERP.
Pick an auth mode
OAuth 2.0 is the right answer for anything that will keep running. In the instance, open Integration → Connected Applications (SM303010), create an application, and choose the Resource Owner Password Credentials flow. That gives you a client ID and secret. Paste both, plus the username and password of the account you want to act as.
Username and password works without any registration and is the fastest way to prove a connection during a first call. It opens a cookie session per connection, so it is the mode most likely to leak sessions if something crashes mid-job. Prefer it for a spike, not for a scene someone leaves open.
Either way the user is a real Acumatica user with real permissions. Create a dedicated one with a read-only role before doing anything else — it is far easier than explaining later why an agent released a document.
The tenant name
The tenant is the login name of the company inside the instance, the one that appears on the sign-in screen when an instance holds more than one. It is:
- optional for REST on a single-tenant instance,
- required for Generic Inquiries, because the OData path contains it,
- appended to the username for OAuth (
admin@MyTenant), since the token endpoint has no company parameter of its own.
A connection that authenticates but returns an HTML page instead of JSON is almost always a wrong tenant or a missing site path, not a broken credential.
The instance URL
Give the root: https://acme.acumatica.com. Self-hosted instances often run under a site path (https://erp.acme.co.uk/AcumaticaERP) — include it. Scheme and trailing slashes are normalized for you.
Endpoint and version
Leave both blank. Default is the endpoint almost everything lives on, and the version is detected by asking your instance which one it answers to. Set them explicitly only when a partner published a custom endpoint you need instead.
Manufacturing entities — production orders, BOMs — live on a separate endpoint named Manufacturing, and only on editions licensed for it. You do not connect twice for this; pass endpoint: "Manufacturing" on the tools that need it. acumatica_discover reports whether it is there.
Verifying
The connection test resolves the endpoint version, which exercises the URL, the credentials, the tenant, and the endpoint's existence in one request. If it passes, acumatica_discover is the next call: it tells you what this particular instance actually contains.