Sign In to the Service

Each time your application starts working with the MYOB Acumatica contract-based REST service, you have to sign in to MYOB Acumatica. To sign in to MYOB Acumatica, you access the needed URL with the POST HTTP method and pass the credentials in the request body. See the following sections for details on the request and the response.

Attention:
If two-factor authentication is turned on for a user account that is used to sign in to MYOB Acumatica through the REST API, this authentication is bypassed by the sign-in method. You can explicitly turn off two-factor authentication for the user accounts that are used only through the REST API by defining the user type of the user account. For details about the creation of a user type to be used by an external application, see To Limit the Number of API Connections of Integrated Applications.
Tip:
Instead of directly signing in to MYOB Acumatica, your application can implement the OAuth 2.0 or OpenID Connect (OIDC) mechanism of authorization. For details about OAuth 2.0 and OIDC, see Authorizing Client Applications to Work with MYOB Acumatica.

HTTP Method and URL

When you need to sign in to MYOB Acumatica, you use the POST HTTP method and the following URL.

POST http://<MYOB Acumatica instance URL>/entity/auth/login

You replace <MYOB Acumatica instance URL> with the URL of your MYOB Acumatica instance.

For example, suppose that you want to sign in to a local MYOB Acumatica instance with the name AcumaticaDB. You should use the following URL: http://localhost/AcumaticaDB/entity/auth/login.

Parameters

You do not need to use parameters when you sign in to MYOB Acumatica.

Request Headers

You have to specify the following header in the request.

Header Description
Content-Type The format of the request body, which can be one of the following:
  • application/json
  • application/x-www-form-urlencoded

Request Body

In the request body, you pass the credentials for accessing MYOB Acumatica in JSON format, as shown in the following example.
{
  "name" : "admin",
  "password" : "123",
  "tenant" : "MyStore",
  "branch" : "MYSTORE",
  "locale" : "EN-US"
}
You specify the values of the parameters as follows:
  • name: The username that the application should use to sign in to MYOB Acumatica, such as "admin".
  • password: The password for the username, such as "123".
  • tenant: The name of the tenant to which the application should sign in, such as "MyStore". You can view the name that should be used for the tenant in the Login Name box of the Tenants (SM203520) form.
  • branch: The ID of the branch to which the application should sign in. You can view the ID of the branch in the Branch ID box of the Branches (CS102000) form.
  • locale: The locale that should be used in MYOB Acumatica. The locale is specified in the System.Globalization.CultureInfo format converted to string, as with "EN-US".
    Attention:
    This parameter has been developed for future use. You do not need to set its value.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a sign-in request.

Code Description
204 The request has been completed successfully. The response headers contain the cookies that authorize the user to make further requests.
400

The data specified in the request is invalid.
429

The number of requests has exceeded the limit imposed by the license (see License Restrictions for API Users).
500

An internal server error has occurred.

Example

The following request shows an example of a sign-in to MYOB Acumatica through the REST API.

Tip:
In the request example below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the URL (that is, you can use https://my.acumatica.com) if the instance is installed in the root of the website.
POST /entity/auth/login HTTP/1.1
Host: [<MYOB Acumatica instance URL>]
Accept: application/json
Content-Type: application/json

{
  "name": "admin",
  "password": "123",
  "tenant": "MyStore",
  "branch": "MYSTORE"
}

Usage Notes

With each subsequent request to the service, the application has to pass the cookies that it has received during sign-in.

For each attempt to sign in to MYOB Acumatica, you must implement the signing out from the service after you finish your work with MYOB Acumatica to close the session. If the session is not closed, you may have issues with subsequent sign-ins to MYOB Acumatica through the REST API. For details about signing out, see Sign Out from the Service.

You should also take into account MYOB Acumatica license API limits. For details, see License Restrictions for API Users.