Authorization Code Flow

When you implement OAuth 2.0 or OIDC authorization in a client application to make the application work with MYOB Advanced, you can use the authorization code flow. With this authorization flow, the client application never gets the credentials of the applicable MYOB Advanced user. After the user is authenticated in MYOB Advanced, the client application receives an authorization code, exchanges it for an access token, and then uses the access token to work with data in MYOB Advanced. When the access token expires, the client application can request a new access token by providing a refresh token.

The following diagram illustrates the authorization code flow, whose steps are described in the sections of this topic.
Figure 1. Authorization code flow


For details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749. For details on the OIDC authorization mechanism, see the specification at https://openid.net/specs/openid-connect-core-1_0.html#Authentication.

Granting Permission to a Client Application

Before an OAuth 2.0 or OIDC client application can work with MYOB Advanced, you must register this application in MYOB Advanced and provide credentials to the application, as described in To Register a Client Application with the Authorization Code Flow. After the registration, you have the client ID and the secret value of the client application.
Important:
  • According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the MYOB Advanced website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the MYOB Advanced website for HTTPS before the OAuth 2.0 client application can work with data in MYOB Advanced. For more information, see Setting Up an HTTPS Service in Web Server (IIS).
  • When you are registering the client application, you have to be logged in to the tenant whose data the client application needs to access.

Connecting to the Authorization Endpoint

The client application connects to the authorization endpoint of MYOB Advanced with the GET method by specifying the following URL with parameters:
  • URL
    The client application can use one of the following options:
    • If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.

      Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
    • The client application can directly use the authorization endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/authorize. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the authorization endpoint address is https://localhost/AcumaticaDB/identity/connect/authorize.

  • URL Parameters
    The client application should specify the following URL parameters.
    Parameter Description
    response_type The type of the flow, which must be set to code for the authorization code flow.
    client_id

    The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID.
    redirect_uri

    The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form.
    scope

    The access scope that is requested by the client application. The scope can be a combination of the following values, delimited by spaces:

    • openid: If this scope is granted, the OpenID Connect protocol is used. Without this scope, the OAuth 2.0 protocol is used.

    • api: Requests access to a web services API or OData interface. If a user grants this scope to the application, the client application can work with the following types of the web services API: contract-based SOAP API, screen-based SOAP API, or contract-based REST API.

      Important: For the contract-based API request, you must specify api for the scope parameter.

      If this scope is granted and the api:concurrent_access scope is not granted, MYOB Advanced manages the sessions of the application through tokens. MYOB Advanced issues the first access token along with the session ID. If the client application requests a new access token by presenting a refresh token, MYOB Advanced reuses the session ID that was issued for the first access token issued with the refresh token. That is, the system uses a single session for each access granted to the client application. For details about the license limitations related to the number of sessions for client applications, see License Restrictions for API Users.

    • offline_access: Requests that a refresh token be granted. If a user grants this scope to the application, MYOB Advanced issues to the client application a refresh token along with the access token. (For information on issuing the access token, see Connecting to the Token Endpoint in this topic.) When the access token has expired, the client application can request a new access token by sending a request to the token endpoint and providing the refresh token. The whole chain for the refresh token expires 30 days after the initial authentication process.
    • api:concurrent_access: Requests permission for the concurrent use of multiple types of web service APIs. If a user grants this scope to the application, the client application can access data in MYOB Advanced in concurrent mode. In this case, MYOB Advanced can maintain multiple sessions for the client application, managing session IDs through cookies. We recommend that the client application request this scope only if concurrent access is required for the client application. For details about the license limitations related to the number of sessions for client applications, see License Restrictions for API Users.
An example of a URL with parameters is shown below. (Line breaks are for display purposes only.)
https://localhost/AcumaticaDB/identity/connect/authorize?
response_type=code
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=http%3A%2F%2Flocalhost%2Fclientapp%2F
&scope=api%20offline_access

Authorizing a User in MYOB Advanced and Granting Access

The authorization endpoint directs the user of the client application to the login page of MYOB Advanced, where the user should enter the credentials to log in to a company configured in the MYOB Advanced instance.

Note: The user must log in to the company that was specified in the client_id URL parameter passed to the authorization endpoint. (This company is selected by default on the login page.)

If the credentials are accepted by MYOB Advanced, the system displays the consent form, where the user can confirm that the application has access to the requested scopes. Only the scopes that were requested by the application are displayed on the consent form.

Receiving the Authorization Code

Once the user grants access to the requested scopes, MYOB Advanced redirects the client application to the redirect_uri address that was specified in the request, and adds the authorization code in the code URL parameter.

Connecting to the Token Endpoint

The client application connects to the token endpoint of MYOB Advanced with the POST method by specifying the following URL, HTTP header, and the following parameters in the request body:

  • URL
    The client application can use one of the following options:
    • If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.

      Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
    • The client application can directly use the token endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/token. In this endpoint, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the token endpoint address is https://localhost/AcumaticaDB/identity/connect/token.

  • HTTP header

    You use the following HTTP header.

    Key Value
    Content-Type application/x-www-form-urlencoded

  • Parameters in the Request Body

    You specify the following parameters in the request body.

    Parameter Description
    grant_type

    The type of the OAuth 2.0 flow, which must be set to authorization_code for the authorization code flow.
    client_id

    The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID.
    code

    The authorization code that the client application has received from the authorization endpoint.
    client_secret

    The value of the secret that was created for the client application during the registration of the application in MYOB Advanced.
    redirect_uri

    The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form.

Receiving the Access Token

MYOB Advanced verifies the provided application credentials and issues the access token, which the client application should provide with each data request to MYOB Advanced. During authentication in MYOB Advanced, if the user has granted to the client application the offline_access scope, MYOB Advanced issues the refresh token along with the access token. A successful response includes the following parameters in the response body.
Parameter Description
token_type The type of the access token, which is Bearer.
access_token The access token.
expires_in The period of time during which the access token is valid.
refresh_token The refresh token. The parameter is returned only if the offline_access scope was granted.

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent request to MYOB Advanced, as shown in the following HTTP example.
GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1
Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc

Refreshing the Access Token

The access token is valid for a specific period of time, which is specified in the response that returns the access token. When the access token expires, the client application can request a new access token by providing the refresh token to the token endpoint. To request a new access token, the client application should use the POST method and have the following URL and the following parameters specified in the request body:

  • URL
    The client application can use one of the following options:
    • If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.

      Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
    • The client application can directly use the token endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/token. In this endpoint, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.

      For example, for a local MYOB Advanced instance with the name AcumaticaDB, the token endpoint address is https://localhost/AcumaticaDB/identity/connect/token.

  • Parameters in the Request Body
    You specify the following parameters in the request body.
    Parameter Description
    grant_type The type of the request, which must be set to refresh_token for the request of the refresh token.
    client_id

    The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID.
    client_secret

    The value of the secret that was created for the client application during the registration of the application in MYOB Advanced.
    refresh_token The refresh token that the client application received from the token endpoint along with the access token if the user granted the offline_access scope to the client application.

Receiving the New Access Token

MYOB Advanced verifies the provided application credentials and issues the new access token and the new refresh token. To request the access token once again, the client application should use the refresh token issued with the previous access token. A successful response includes the following parameters in the response body.
Parameter Description
token_type The type of the access token, which is Bearer.
access_token The access token.
expires_in The period of time during which the access token is valid.
refresh_token The refresh token.

Logging Out from MYOB Advanced

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should directly call the logout method of the MYOB Advanced web services API when the application finishes its work with MYOB Advanced. The client application does this by using the POST method, the ASP.NET_SessionId cookie with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout
In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect.