Complete Developer Guide: OAuth 2.0 Authorization Code Flow in MYOB Acumatica

Introduction

MYOB Acumatica API authentication allows external applications to securely access ERP data without collecting or storing a user’s MYOB Acumatica login credentials.

MYOB Acumatica supports OAuth 2.0 authentication for integrations involving SaaS platforms, ecommerce applications, CRM systems, warehouse management software and custom business applications.

In the Authorization Code Flow, the user signs in directly to MYOB Acumatica, approves access and returns an authorization code to the connected application.

The application then exchanges that code for an access token and, when the offline_access scope is granted, a refresh token.

The access token is used to call the MYOB Acumatica REST API, while the refresh token allows the application to obtain a new access token without asking the user to reconnect every time the original token expires.

This guide explains how to:

• Register a Connected Application in MYOB Acumatica
• Generate the correct tenant-specific client ID
• Configure the client secret and redirect URI
• Build an OAuth 2.0 authorization request
• Exchange an authorization code for tokens
• Refresh an expired access token
• Make authenticated MYOB Acumatica API requests
• Troubleshoot common OAuth errors

The Authorization Code Flow keeps the user’s credentials outside the client application and supports access and refresh tokens for continuing API operations.

👉

For businesses building deep integrations across MYOB products, see our full offering here: MYOB Integration Services

.

Prerequisites

Before starting the MYOB Acumatica OAuth 2.0 setup, ensure that you have:

• Administrative access to the required MYOB Acumatica tenant
• Permission to open and manage the Connected Applications screen
• The complete MYOB Acumatica instance URL
• HTTPS enabled for the production application
• A confirmed callback or redirect URI
  • • A secure server-side location for storing client secrets and tokens
• The correct company or tenant selected when registering the application
• A tool such as Postman, cURL or an API client for testing requests

After saving the Connected Application, copy the complete client ID exactly as generated. It normally follows a format similar to:

<GUID>@<Tenant-or-Company-ID>

The tenant or company suffix determines which MYOB Acumatica tenant the integration can access. Do not remove the suffix or manually replace it with a different tenant name.

MYOB Acumatica OAuth 2.0 Authentication Options

MYOB Acumatica supports multiple OAuth 2.0 and OpenID Connect flows. The right option depends on the application type, whether a user is available to approve access, and whether the integration needs continuing access through refresh tokens.

For most web applications and SaaS integrations accessing MYOB Acumatica on behalf of a user, the Authorization Code Flow is the most relevant option.

1. Authorization Code Flow

Best suited for:

• SaaS applications
• Web applications
• Multi-user integrations
• Ecommerce, CRM and operational system integrations
• Applications requiring refresh tokens
• Integrations accessing MYOB Acumatica on behalf of a use

How it works:

1. User logs in via MYOB Acumatica
2. System issues an authorization code
3. Your app exchanges the code for Access Token + Refresh Token
4. Tokens are stored securely for API access

Why prefer this flow?

• Most secure
• Supports refresh tokens
• Required for MYOB Marketplace apps
• Industry-standard for 3rd-party integrations

2. Implicit Flow

Legacy flow used for browser-only apps.

MYOB Acumatica still supports it, but

• No refresh tokens
• Lower security
• Not recommended for new integrations

3. Resource Owner Password Credentials Flow

This flow sends user credentials (user/pass) directly to your app.

⚠ Not recommended

Only use if integrating with legacy systems that cannot handle OAuth redirects.

Steps to Set Up Authorization Code Flow (OAuth 2.0)

Sign in to the MYOB Acumatica tenant whose data the application needs to access.

1. Register a Connected Application in MYOB Acumatica Instance

Navigate to More Items → Integrations → Connected Applications

1. Click + Add New
   

   

2. Select Authorization Code as OAuth type
   

   

3. Save → Copy your Client ID
   

   

Create Client Secret

1. Click Add Shared Secret
   

   

2. Add description
   

   

3. Leave expiry blank
4. Copy the secret value immediately

Set Redirect URI

Add the callback URL for OAuth return:

https://yourapp.com/oauth/callback
https://localhost:3000/auth

2. Connect to the MYOB Acumatica Authorization Endpoint

Add a “Connect to MYOB Acumatica” button in your UI that begins the OAuth process.

Your app redirects the user to MYOB Acumatica using:

Authorization Endpoint

https://yourapp.com/identity/connect/authorize

Query parameters:

• response_type=code
• client_id=<your_client_id> + must include the company ID suffix
  • You must use: <client_id>@<CompanyId>
  • Example CompanyId: XXXXXXX
  • How to get CompanyId? The unique identifier for the company file you are working with. You can retrieve this through the MYOB API too.
    

    

  • redirect_uri=<your_registered_redirect_uri>
  • scope=offline_access

Example Authorization Request

https://mycompany.myobacumatica.com/identity/connect/authorize?response_type=code
&client_id=01336912-1A06-810B-1F3D-E24FE3323287@AU Demo Data
&redirect_uri=https://satvasolutions.com/oauth/callback
&scope=api offline_access

3. User Logs Into MYOB Acumatica & Grants Access

• You will be prompted to log in using your MYOB username and password.
  

  

• Grant Access:
  • After entering your credentials, a screen will appear asking for permission to allow access to your application.
  • Click Allow Access to grant the required permissions.
    

    

4. Exchange the Authorization Code for an Access Token

• If the user approves, Acumatica redirects back to your redirect_uri and includes:
• After permission, MYOB redirects to your redirect_uri with:
• ?code=<authorization-code>
• Next, your app must exchange this code for tokens.

Exchange Code for Token:

• Token Endpoint: https://<acumatica-url>/identity/connect/token

Query parameters:

• grant_type=authorization_code
• client_id=<your_client_id> + must include the company ID suffix
• client_secret= <your_client_secret>
• Code={{AUTH_CODE_VALUE}}
• redirect_uri=<redirect_uri>

Token Request Example

grant_type=authorization_code
&client_id=01336912-1A06-810B-1F3D-E24FE3323287@AU Demo Data
&client_secret=YOUR_CLIENT_SECRET
&code=AUTH_CODE_VALUE
&redirect_uri=https://satvasolutions.com/

Successful Token Response Example

Acumatica ERP verifies the provided application credentials and issues the access token, which the client application should provide with each data request to Acumatica ERP.

A successful response includes the following parameters in the response body

Below is a typical JSON response:

  {
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

How to Refresh an MYOB Acumatica Access Token

MYOB Acumatica access tokens are issued for a limited period. When an access token expires, the application can request a new one using the refresh token received during the original token exchange.

A refresh token is returned when:

• The application requests the offline_access scope
• The user grants that scope
• Refresh tokens are enabled for the Connected Application

Send a POST request to the same token endpoint:

https://<MYOB-Acumatica-instance>/identity/connect/token

Use this form-encoded request body:

grant_type=refresh_token
client_id=<complete-generated-client-id>
client_secret=<client-secret>
refresh_token=<current-refresh-token>

Example:

curl --request POST \
  --url "https://mycompany.myobacumatica.com/identity/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=01336912-1A06-810B-1F3D-E24FE3323287@AU Demo Data" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "refresh_token=CURRENT_REFRESH_TOKEN"

MYOB Acumatica can return both a new access token and a new refresh token. When a new refresh token is returned, replace the previously stored value so that the application does not continue using an outdated token.

The application should also handle expired, revoked or invalid refresh tokens by asking the user to reconnect the integration.

5. Request Data Using the Access Token

Every request must include:

Authorization: Bearer <access_token>

Example request for Account:

GET /entity/Default/18.200.001/Account
Host: Acumatica Site URL
Authorization: Bearer {{access_token}}

Common MYOB Acumatica OAuth 2.0 Errors and Fixes

invalid_client

This error commonly occurs when the client ID or client secret is incorrect.

Check that:

• The complete client ID was copied
• The tenant suffix after @ is present
• The correct client secret is being used
• The Connected Application is active
• The application was registered in the intended tenant

Redirect URI mismatch

The redirect URI must match the registered value exactly.

Check the:

• http or https protocol
• Domain
• Port
• URL path
• Trailing slash
• URL encoding

Use the same value in the authorization request and token request.

invalid_grant

This can occur when:

• The authorization code has expired
• The code has already been used
• The redirect URI differs from the original request
• The code was issued for another client or tenant
• The PKCE code_verifier does not match the original challenge

Restart the authorization process and generate a new code.

Refresh token is not returned

Confirm that:

• offline_access was included in the scope
• The user approved offline access
• Refresh tokens are enabled for the Connected Application
• The Authorization Code Flow was selected

401 Unauthorized

Confirm that the access token is active and is included as:

Authorization: Bearer <access-token>

Also verify the instance URL, tenant, API permissions and endpoint version.

User is directed to the wrong tenant

The tenant is determined by the suffix included in the generated client ID. Register or use a Connected Application created under the correct tenant instead of manually changing the suffix.

MYOB Acumatica Developer Certification Requirements

To get official MYOB Partner Support, you need to get a developer certification via the “MYOB Academy” to understand the platform and the endpoints available.

The online API course takes around 3-4 hours to complete.

Certification Details

• Course: API Training Certification
• Duration: 3–4 hours (online, self-paced)
• Platform: https://academy.myob.com/
• To enroll, email educationteam@myob.com requesting access to the course.

Once your developer passes the certification:

• You gain access to the MYOB Partner Support Portal
• You can raise API-related support tickets
• Your partner portal is activated for technical support

Our Certification

We have completed the specified API course and passed the test successfully.

The purpose of completing the certification is to gain the ability to raise support cases through the MYOB Partner Support Portal.

Certification activates partner-level support access.

After completing the certification, we now have a Partner Portal account and can create support tickets here: Acumatica Partner Portal

MYOB Acumatica OAuth 2.0 Setup Checklist

Before moving the integration to production, verify that:

• The Connected Application was created in the correct tenant
• Authorization Code was selected as the OAuth flow
• The complete generated client ID was copied
• The client secret is stored securely
• The redirect URI matches exactly
• The authorization endpoint uses the MYOB Acumatica instance domain
• The token request uses the POST method
• The request uses application/x-www-form-urlencoded
• The api scope is included
• offline_access is requested when refresh tokens are required
• The state value is generated and validated
• PKCE uses S256 where applicable
• New refresh tokens replace previously stored refresh tokens
• The REST endpoint version is enabled in the target instance
• Expired and revoked tokens are handled appropriately

Conclusion

Implementing OAuth 2.0 Authorization Code Flow in MYOB Acumatica requires more than generating an access token. A reliable integration must use the correct tenant-specific client ID, an exact redirect URI, a secure token exchange and a controlled refresh-token process.

Before deploying the integration, validate the Connected Application configuration, token storage, secret rotation, error handling, tenant selection and REST endpoint version.

These controls help the application maintain secure and dependable access to MYOB Acumatica data across ecommerce, CRM, inventory, warehouse, payroll and custom business workflows.

FAQs

What is OAuth 2.0 Authorization Code Flow in MYOB Acumatica?

OAuth 2.0 Authorization Code Flow allows an external application to access MYOB Acumatica data without storing the user’s login credentials. The user signs in, grants permission, and the application exchanges an authorization code for an access token.

How do I authenticate with the MYOB Acumatica API?

To authenticate with the MYOB Acumatica API, create a Connected Application, configure the redirect URI, generate a client ID and client secret, request an authorization code, and exchange it for an access token through the token endpoint.

How do I generate an access token in MYOB Acumatica?

Send the authorization code to the MYOB Acumatica token endpoint using a POST request. Include the client ID, client secret, authorization code, redirect URI, and authorization_code grant type in the form-encoded request body.

What is the MYOB Acumatica OAuth authorization endpoint?

The authorization endpoint is hosted on the MYOB Acumatica instance:

https://<MYOB-Acumatica-instance>/identity/connect/authorize

The request normally includes the client ID, redirect URI, scope, response type, and state value.

How do I refresh an expired MYOB Acumatica access token?

Submit the refresh token to the token endpoint with grant_type=refresh_token. Include the client ID, client secret, and current refresh token. Store any newly returned refresh token because the previous token may no longer remain valid.

Why is MYOB Acumatica not returning a refresh token?

A refresh token may not be returned when the offline_access scope is missing, the user has not approved offline access, or refresh tokens are not enabled in the Connected Application configuration.

How can I fix a redirect URI mismatch in MYOB Acumatica?

Confirm that the redirect URI exactly matches the value registered in the Connected Application. Check the protocol, domain, port, path, trailing slash, and URL encoding in both the authorization and token requests.

What causes a 401 Unauthorized error in the MYOB Acumatica API?

A 401 error may occur because the access token has expired, the wrong tenant-specific client ID was used, the Bearer prefix is missing, the application lacks permission, or the request targets the wrong MYOB Acumatica instance.