Resource Owner Password Credentials Flow

When you implement OAuth 2.0 authorization in a client application to make the application work with MYOB Advanced, you can use the resource owner password credentials flow.

With the resource owner password credentials flow, the credentials (username and password) of the MYOB Advanced user are provided directly to the client application, which uses the credentials to obtain the access token. When the access token expires, the client application can request a new access token by providing a refresh token.

The following diagram illustrates the resource owner password credentials flow, whose steps are described in the sections later in this topic.
Figure 1. Resource owner password credentials flow


For details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749.

Granting Permission to a Client Application

Before an OAuth 2.0 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 Resource Owner Password Flow. After the registration, you have the client ID and 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.

Obtaining the Credentials of the MYOB Advanced User

The client application should obtain the username and password of the applicable MYOB Advanced user, which can then be exchanged for an access token.

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 password for the resource owner password credentials 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.
    client_secret

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

    The username of an MYOB Advanced user.

    password

    The password for the specified username.
    scope

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

    • 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 request is shown below. (Line breaks are for display purposes only.)

POST / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/identity/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
client_id=8E0761D9-F4EC-2D4B-A60F-BCE2708C6FDD%40CompanyB&
client_secret=O19LLT5Z0SzFbCIKLXLqQQ&username=admin&
password=123&scope=api+offline_access

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.