# Fixing Epicor REST v2 API 401 Unauthorized Errors > Source: https://netray.co/erp-help/epicor-rest-v2-api-401-unauthorized-fix > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: ERP Help ## 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. ## Kind error ## System epicor ## Erp Epicor Kinetic / Epicor ERP 10 ## Module REST API v2 / Integration ## Query Epicor REST v2 API 401 Unauthorized error ## Alternate Queries - 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 ## Applies To Epicor ERP 10.2.400+, Epicor Kinetic 2021.1 through 2024.2, REST API v2 (OData v4) ## Steps ### Diagnose the 401 **Items:** Confirm 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. Check 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. Confirm 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. Confirm 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. Check 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. Verify 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. If 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. ## Sections ### How Epicor REST v2 authentication actually works **Body:** 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 **Body:** 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. **Code:** - GET https://server/instance/api/v2/odata/CompanyID/Erp.BO.SalesOrderSvc/SalesOrders x-api-key: Authorization: Basic ### Testing outside your integration tool first **Body:** 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. ## 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. ## Ai Angle 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. ## Faq ### Do I need both an API key and user credentials for every REST v2 call? **Answer:** 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? **Answer:** 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? **Answer:** 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? **Answer:** 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. ## Search terms Epicor REST v2 401 Unauthorized, Epicor REST API key error, Epicor x-api-key header, Epicor api/v2/odata authentication, Epicor REST API OAuth, Epicor Basic auth REST API, Epicor integration 401 error, Epicor REST API help page, Epicor Application Studio API key, Epicor REST API 403 vs 401 --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json