Fixing Epicor REST v2 API 401 Unauthorized Errors
Epicor REST v2 API 401 Unauthorized error
Also searched as
- Epicor REST API key invalid or missing
- Epicor api/v2/odata 401 error fix
- Epicor REST API authentication basic auth vs api key
- Epicor x-api-key header not working
Short answer
A 401 Unauthorized calling Epicor's REST v2 (api/v2/odata) endpoint almost always comes down to one of three things: a missing or wrong x-api-key header, valid credentials but an API key scoped to a different company than the one in the URL, or REST services simply not enabled for that endpoint. Confirm the API key exists and is active in Application Studio (or the classic REST API help page), matches the company segment in the URL, and that the account used for Basic auth or OAuth has the right security group.
Applies to: Epicor ERP 10.2.400+, Epicor Kinetic 2021.1 through 2024.2, REST API v2 (OData v4)
Diagnose the 401
- 1Confirm the URL company segment matches the API key's scope - api/v2/odata/{Company}/... where Company must be one the API key was created for, or the key must be scoped to All Companies.
- 2Check the API key itself in Application Studio (Admin Tools / API Keys, naming varies by version) - confirm it exists, is not expired or revoked, and is tied to the correct application.
- 3Confirm the request includes the x-api-key header with the raw key value, not the key's description or ID, and that no extra whitespace or quoting was added by the calling tool.
- 4Confirm the Authorization header carries valid credentials for the integration - Basic auth with a base64 user:password, or a bearer token if OAuth 2.0 is configured - and that the account is not locked, disabled, or missing an Epicor license.
- 5Check that the integration/service account has the security group and Company Access rights for the company and the specific business object (for example SalesOrderSvc) you are calling; a valid login with no rights to that object also returns 401 or 403 depending on version.
- 6Verify REST services are actually enabled and pointed at the right AppServer/app pool in IIS - a REST endpoint can be reachable but misconfigured if it is pointing at a different Epicor instance than the API key was created against.
- 7If using a reverse proxy or API gateway in front of Epicor, confirm it is not stripping the x-api-key or Authorization headers before they reach the Epicor REST service.
How Epicor REST v2 authentication actually works
Epicor REST v2 typically requires two things together: an API key sent as the x-api-key header, which identifies the calling application and its company scope, and a set of user credentials, sent either as Basic auth (base64-encoded user:password) or as an OAuth 2.0 bearer token depending on how the environment is configured. Missing either one produces a 401, and the error text alone often does not tell you which of the two is the actual gap.
The API key is created and managed separately from user accounts - in Application Studio in newer Kinetic versions, or from the REST API help page (https://{server}/{instance}/api/help) in earlier 10.2 releases - and it can be scoped to a single company, several companies, or all companies. A key scoped to company A used against a URL for company B is a valid key that still returns 401 for that specific call.
Distinguishing 401 from 403
A 401 generally means Epicor could not authenticate the request at all - wrong or missing api key, bad credentials, or an expired token. A 403 usually means Epicor authenticated the caller successfully but that account lacks rights to the object or company being requested. If you are seeing 403 instead of 401, the fix is almost always in Company Maintenance security or the user's security group / BO rights rather than the API key.
GET https://server/instance/api/v2/odata/CompanyID/Erp.BO.SalesOrderSvc/SalesOrders x-api-key: <raw key value> Authorization: Basic <base64 user:password>
Testing outside your integration tool first
Before debugging the calling application, reproduce the exact call in Postman or curl with the same URL, headers, and credentials. This isolates whether the problem is Epicor's configuration or something the integration tool is doing - a common surprise is an integration platform that silently URL-encodes or trims the x-api-key value, producing a key that looks right in logs but does not match on the server.
Common pitfalls
- !Assuming the API key alone is authentication - it identifies the application, it does not replace a valid user login.
- !Using an API key scoped to one company against a different company's URL segment and assuming the key itself is broken.
- !Confusing 401 (authentication failure) with 403 (authorization/rights failure) and debugging the wrong layer.
- !Rotating or regenerating an API key without updating every integration that references the old value, which turns one 401 into several at once.
- !Not checking that the service account used for integration credentials still has an active Epicor license - a disabled or unlicensed account authenticates to nothing.
- !Testing only through the integration middleware, which can mask whether the raw REST call itself is correct.
How an ERP-grounded AI assistant handles this
ERPray can be pointed at the integration's request logs and Epicor's REST/security configuration to answer "why is this integration getting 401" by checking, in order, whether the api key is valid and scoped to the right company, whether the credentials are being sent correctly, and whether the account has BO rights for the endpoint - the same triage sequence an integration developer would run by hand, surfaced as a direct answer rather than a multi-tab investigation.
Frequently asked questions
Do I need both an API key and user credentials for every REST v2 call?
In most Epicor 10.2/Kinetic configurations, yes - the API key identifies the calling application and its company scope, while separate Basic auth or OAuth credentials authenticate the acting user. Some environments configure OAuth client credentials flow instead of per-user Basic auth, but the API key requirement is independent of that choice.
Can one API key be used across multiple integrations?
Technically yes, but it is not good practice - a single shared key makes it impossible to see which integration is generating a given call in logs, and revoking it to respond to one integration going bad breaks every integration using it. Create a separate key per integration.
Where do I find or create an API key in Kinetic?
In current Kinetic versions this is typically under Application Studio's API Key management or the System Setup / Security area, naming varies by release; in classic 10.2 it was usually accessible from the REST API help page at /api/help on your instance. If you cannot find it, your Epicor administrator or partner can confirm the exact path for your version.
Why does the same API key work in Postman but not from our middleware?
Almost always header handling - the middleware may be trimming, re-encoding, or dropping the x-api-key or Authorization header. Capture the raw outgoing HTTP request from the middleware (not just the configured value) and diff it against the working Postman request byte for byte.
Related
Fixing Epicor BusinessObjectException: BPM Directive Errors
A BusinessObjectException that says "A Business Process Management (BPM) directive has raised the following error" means a directive on that business object stopped the transaction, either deliberately via a Raise Exception widget or accidentally via an unhandled .NET error in Custom Code. Expand the InnerException on the error dialog to see the real message and the directive name, then open BPM Designer for that object and method to find the widget that fired.
How-toFixing a Slow Epicor BAQ (Business Activity Query)
A slow BAQ in Epicor is usually caused by unindexed join columns, a subquery or calculated field forcing a table scan, or the BAQ pulling far more rows than the dashboard actually displays before filtering client-side. Fix it by reading the SQL Server execution plan Epicor generates, moving filters into the BAQ criteria instead of the dashboard filter panel, and replacing subqueries with joins where possible.
How-toEpicor MRP Runs but Generates No Suggestions
When Epicor's MRP process completes without a job or purchase suggestion for a part you expect one for, the cause is almost always the part's own configuration (Part Class Type, Make Direct, Non-MRP flag, planning Time Fence) or the demand not being linked in a way MRP recognizes, not a defect in the MRP engine. Work through the part's Planning tab, its safety stock and lead time setup, and the demand source (sales order line status, job material requirement) before assuming the run itself failed.
How-toPreserving Customizations When Upgrading to Epicor Kinetic
Epicor Kinetic's web UI does not simply inherit classic smart-client customizations - most need to go through the Update Customization / Application Studio conversion process, and some WinForms-specific customizations cannot convert directly and must be rebuilt in the Kinetic designer. Plan the upgrade as a customization inventory and rework project, not a single technical cutover step.
AdvancedHow to create and call an Epicor Function
Open Function Studio from the main menu (Customization > Function Studio) or from inside a BPM designer's Call Context widget, define a Library and Function with typed inputs/outputs, write the logic in the C# widget, then compile and test with the built-in test harness before calling it from a BPM directive, a dashboard, or another function.
AdvancedEpicor Application Studio: understanding customization layers
Kinetic UI is built in layers loaded in order - Base (Epicor-delivered), Customization (Application Studio, company/layer-wide), Personalization (user- or role-specific, applied on top), and optionally Extended (packaged add-on layers) - and a change you make will not appear if a higher layer overrides the same control or if you are testing in the wrong layer context.
AI for ERPAI for Epicor Kinetic, Beyond What Prism Covers
Add AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.
Stuck on Epicor Kinetic / Epicor ERP 10?
Talk to engineers who work inside Epicor Kinetic / Epicor ERP 10 every week, and who build private AI that answers these questions from your own ERP data.