Resource Owner Password Credentials Flow

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

With the resource owner password credentials flow, the credentials (username and password) of the MYOB Acumatica 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 Acumatica, you must register this application in MYOB Acumatica 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 Acumatica website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the MYOB Acumatica website for HTTPS before the OAuth 2.0 client application can work with data in MYOB Acumatica. 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 Acumatica User

The client application should obtain the username and password of the applicable MYOB Acumatica 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 Acumatica 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 Acumatica instance URL>/identity/. In this address, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance to which the client application is going to connect.

      For example, for a local MYOB Acumatica 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 Acumatica instance URL>/identity/connect/token. In this endpoint, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance to which the client application is going to connect.

      For example, for a local MYOB Acumatica 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 Acumatica. 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 Acumatica.
    username

    The username of an MYOB Acumatica 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 Acumatica manages the sessions of the application through tokens. MYOB Acumatica 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 Acumatica 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 Acumatica 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 Acumatica in concurrent mode. In this case, MYOB Acumatica 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 Acumatica verifies the provided application credentials and issues the access token, which the client application should provide with each data request to MYOB Acumatica. During authentication in MYOB Acumatica, if the user has granted to the client application the offline_access scope, MYOB Acumatica 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 Acumatica, 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 Acumatica instance URL>/identity/. In this address, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance to which the client application is going to connect.

      For example, for a local MYOB Acumatica 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 Acumatica instance URL>/identity/connect/token. In this endpoint, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance to which the client application is going to connect.

      For example, for a local MYOB Acumatica 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 Acumatica. 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 Acumatica.
    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 Acumatica 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 Acumatica

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 Acumatica web services API when the application finishes its work with MYOB Acumatica. 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.