Acumatica REST API 401 Unauthorized and API Login Limit: How to Fix
Acumatica REST API 401 unauthorized login
Also searched as
- Acumatica API login limit exceeded
- Acumatica entity auth login 401
- Acumatica API session not logged out
- Acumatica OAuth connected application token
Short answer
A 401 from the Acumatica contract-based REST API usually means the login call failed or the session cookie was not sent back, and an API login limit error means too many API sessions are open for your license. Post to /entity/auth/login with name, password and company, reuse the cookie, and always call /entity/auth/logout when done. For integrations, prefer OAuth 2.0 through a Connected Application.
Applies to: Acumatica Cloud ERP contract-based REST API (default endpoint and custom endpoints), cookie login and OAuth 2.0 flows, SaaS and on-premises
How to fix 401 and login-limit errors
- 1Confirm the base URL includes the instance path, for example https://host/Instance/entity/auth/login, not just the host name.
- 2POST JSON with name, password and company (the tenant or company login name, which must be exact when the instance has more than one tenant).
- 3Capture the Set-Cookie response and send it with every later call. Clients that drop cookies get 401 on the second request.
- 4Check the user is enabled, not locked, has a role with access to the entities you call, and that the account is not forced to change its password at next login.
- 5If the instance enforces two-factor authentication, an API user with password login will fail; use OAuth 2.0 with a Connected Application instead.
- 6Always call POST /entity/auth/logout in a finally block so sessions are released; unclosed sessions count against the API user limit until they time out.
- 7For a limit error, open the License Monitoring Console to see current API users and request rates, then add pooling, fewer parallel logins, or request a license tier change.
- 8In Connected Applications (SM303010), create the client, choose the flow, and verify the scope is api and the redirect URI matches exactly.
Cookie login that works
The classic login is a POST to /entity/auth/login with a JSON body. The response sets session cookies that carry the identity for the rest of the conversation. If you use a typed HTTP client, enable a cookie container and keep one client instance per session.
If your company name is wrong, the call returns an error that looks like a bad password. When a single tenant exists you may omit company, but with multiple tenants it is required.
POST https://host/Instance/entity/auth/login
Content-Type: application/json
{
"name": "apiuser",
"password": "********",
"company": "Tenant1"
}
POST https://host/Instance/entity/auth/logoutWhy 401 appears after it worked
Sessions expire. Idle API sessions time out, and a long import can outlast the session. Handle a 401 by logging in again once and retrying, not by looping indefinitely.
Concurrency is the next cause. Acumatica ties API access to your license, which has limits on concurrent API users and requests per minute. Parallel workers each logging in with the same account can hit those limits; use one session per worker and reuse it.
Finally, role and endpoint issues. A user can authenticate but still be denied on an entity if the roles do not grant the screen behind it. That usually returns 403 or a screen access error rather than a login failure, so read the response body.
OAuth 2.0 for integrations
For new integrations, register a Connected Application on SM303010. Pick the flow that matches the client: Authorization Code for interactive apps, Client Credentials for service to service where available in your version, or Resource Owner Password only for legacy cases.
Request the api scope, store the client secret outside the code, and refresh tokens before they expire. OAuth avoids sending the user password on each call and works with two-factor authenticated tenants.
Common pitfalls
- !Forgetting to log out, which leaves sessions open and exhausts the API user limit.
- !Using the host URL without the instance virtual directory.
- !Sharing one integration account across many parallel workers and hitting concurrency or request limits.
- !Hard coding a password for an account with two-factor authentication enabled.
- !Retrying 401 in a tight loop, which can lock the account.
How an ERP-grounded AI assistant handles this
An AI assistant over Acumatica can read the response body, tell you whether it is a credentials, tenant name, role or limit problem, and show the exact call that works. For reporting questions, ERPray reads through the API in read-only mode with its own scoped account, so analysts are not sharing an integration login.
Frequently asked questions
What does the company field in the login body mean?
It is the tenant or company login name chosen on the Acumatica sign-in screen, not the legal company name. On a single tenant instance it can be omitted, but on multi tenant instances a wrong value fails with a credentials style error.
How many API sessions can I open?
It depends on your license. The License Monitoring Console shows the allowed concurrent API users and request rates. Plan integrations to reuse sessions and log out, and ask your Acumatica partner if you need a higher tier.
Should I use OAuth or cookie login?
Use OAuth 2.0 through a Connected Application for new integrations, since it avoids password handling and works with two-factor authentication. Cookie login is fine for quick scripts and internal tools on a test tenant.
Why do I get 401 only on the second call?
The client is not sending the session cookie back. Use an HTTP client with a cookie container, keep the same instance for the whole session, and do not strip cookies in proxies or API gateways.
Related
How to Create an Import Scenario in Acumatica
Import scenarios in Acumatica live under System Integration > Import Scenarios: you pick a source (a file or a Generic Inquiry), map each source field to a target DAC field on the destination screen, then run or schedule the scenario. A small sample file run through the wizard first makes the field mapping step far faster than mapping blind.
How-toHow to Create a Generic Inquiry in Acumatica
Generic Inquiries (GI) are Acumatica's no-code query builder for joining tables, adding filters, and exposing the result as an inquiry screen, dashboard data source, or API endpoint. Open System > Customization > Generic Inquiry, add your base table, define joins and conditions, then run and save. No SQL or customization project is required.
Error fixAcumatica Customization Project Publish Failed: How to Fix It
A failed publish in Acumatica means the platform could not validate, compile or apply the customization package to the website and database. Open the Publish Customization Project dialog, read the Compilation log and the Validation log, fix the first error (usually a C# compile error, a missing DAC field or a conflicting project), and publish again, ideally on a test tenant first.
Error fixFix Odoo AccessError: You Are Not Allowed to Access Records
Odoo raises AccessError when a user's security groups do not grant a CRUD right on a model through ir.model.access.csv, or when an ir.rule record rule filters the specific record out for that user or company. Fix it by adding the user to the group named in the error, editing the model's access rights, or reviewing the record rule's domain under Settings > Technical > Security.
How-toHow to Void a Check in Sage 100
Sage 100 voids checks through Accounts Payable > Main > Check and Payment Voiding. Select the bank code, choose the check number, and Sage reverses the Cash Disbursements Journal entry and reopens the invoice it paid. A check that already cleared in Bank Reconciliation or falls in a closed period needs an extra step before it can be voided cleanly.
How-toHow to Run Requirements Planning (MRP) in SYSPRO
SYSPRO's MRP engine lives under Planning and Scheduling > Requirements Planning. Set planning parameters per warehouse, run the Requirements Calculation to net demand against supply, then review and release the resulting suggestions as purchase requisitions or work orders. A full regenerative run typically runs on a schedule, with net change runs in between to pick up new activity.
AI for ERPAI for Acumatica Manufacturing Edition, Built on Your Own Data
Add AI to Acumatica Manufacturing Edition without giving up control of your shop and cost data. Private LLMs and agents grounded in your Acumatica instance.
Stuck on Acumatica Cloud ERP?
Talk to engineers who work inside Acumatica Cloud ERP every week, and who build private AI that answers these questions from your own ERP data.