Call Manhattan Active® API

• 1: Authenticate to Manhattan Active® API
• 2: Call Manhattan Active® API from your code
• 3: Call Manhattan Active® API using Postman
• 4: Manhattan Active® API Reference

1 - Authenticate to Manhattan Active® API

Before you begin

Before authenticating to an API, it is necessary to have an authorized user (OAuth resource owner) and an OAuth client.

Authentication information

Manhattan Active® API supports the following OAuth 2.0 authorization grants (OAuth flows):

• Authorization Code Grant (web server flow)
• Resource Owner Password Credentials Grant (password flow)

Please contact your organization’s Manhattan Active® Platform administrator for the following OAuth settings:

Authenticate from your code

For access to Manhattan Active® API from your software, please see Call from your code

Authenticate using Postman

For access to Manhattan Active® API from Postman, please see Call using Postman

What’s next

To learn more about calling an individual Manhattan Active® API, please see the REST API documentation in our product sites:

• MA Active Supply Chain
• MA Active Omni

2 - Call Manhattan Active® API from your code

This how-to guide will walk you through a very simple Python command line utility (CLI). The utility will obtain an access token for Manhattan Active® API using the OAuth 2.0 Resource Owner Password Credentials Grant. That token will then be used to call the following to get information for the authenticated user:

GET /api/organization/user/allDetails/userId/

Before you begin

Before beginning, please assemble the authentication information.

Obtain an access token

The OAuth 2.0 Resource Owner Password Credentials Grant (direct access) may be used to obtain an API access token. The token endpoint may be called as follows:

def access_token(client_id, client_secret, token_url, username, password):
    """Return access token for Manhattan Active® API using the resource owner password credentials grant

    Conforms to https://datatracker.ietf.org/doc/html/rfc6749#section-4.3

    Must authenticate to token endpoint with client credentials:
    https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1

    Args:
      client_id (str): client identifier <Consult your Administrator to obtain one>
      client_secret (str): client password <Consult your Administrator to obtain one>
      token_url (str): endpoint to obtain access token
      username (str): the resource owner username
      password (str): the resource owner password

    Returns:
      string: access token

    Raises
       HTTPError:  http error
    """

    # Access Token Request:  https://datatracker.ietf.org/doc/html/rfc6749#section-4.3.2
    response = requests.post(token_url, data={
        "grant_type": "password",
        "username": username, "password": password},
        auth=(client_id, client_secret))
    response.raise_for_status()
    return response.json()["access_token"]

Call an API

To call the API, obtain an access token above and place it in the Authorization header as a Bearer token:

url = api + "/organization/api/organization/user/allDetails/userId/" + username

response = requests.request(
    "GET", url, headers={'Authorization': 'Bearer ' + token}, data={})
response.raise_for_status()

print(json.dumps(response.json(), indent=2))

Run the code

Download the source code

Download the user.py python source code.

Install requests module

python3 -m pip install requests==2.27.1 

Set environment variables

Environment variables may be used to store common information:

For example:

export ACTIVE_USERNAME=user@example.com
export ACTIVE_CLIENT_ID=<Custom_Client_Id_Created_By_Your_Administrator>

Run CLI

Run the user.py script to obtain information for the authenticated user.

# See help for getting user info
python3 user.py -h

# Sample call (assumes ACTIVE_PASSWORD and ACTIVE_CLIENT_SECRET environment variables set)
python3 user.py \
 -c <Consult your Administrator to obtain the client_id> \
 -t https://<environment>-auth.omni.manh.com/oauth/token \
 -u user@system.com \
 -a https://<environment>.omni.manh.com

Troubleshooting

If you receive a 400 Client Error: for url: https://...-auth.omni.manh.com/oauth/token, then your username and password are invalid for the authorization server.

3 - Call Manhattan Active® API using Postman

This guide will walk you through the steps for invoking an example REST API exposed by Manhattan Active®. The steps below will also assist you in establishing the authorization using OAuth v2.0 for invoking the API.

Before You Begin

• Download and install Postman or an equivalent tool of your choice. If you already have Postman installed, update it to v9.0.9 or newer.
• You will need the following information from the administrator who manages the implementation of Manhattan Active® applications for you:
  1. Application URL such as https://<unique_id>.omni.manh.com or https://<unique_id>.sce.manh.com or https://<unique_id>.scp.manh.com. We will use https://example.omni.manh.com for this document.
  2. Authorization Server URL such as https://<unique_id>-auth.omni.manh.com or https://<unique_id>-auth.sce.manh.com or https://<unique_id>-auth.scp.manh.com. We will use https://example-auth.omni.manh.com for this document.
  3. Values of client_id and client_secret parameters as configured by your administrator. Your administrator will need to create a custom client_id (documented elsewhere already) to be used with Postman. The administrator can look up the value of the respective client_secret. We will refer the client_secret as <client_secret> as the value of client_secret for this document. Please use your own client_secret value exclusive for your use cases.
  4. A valid username and password for you to authenticate yourself. We will use jerrythomas@example.com and p455w0rd respectively as the username and password for this document. These are not valid credentials at all. Please use valid credentials for your purposes.
• As a sample REST API, we will use the endpoint that returns the details of your user. You may replace it with any other REST API that you have access to.

Steps

The step-by-step instructions below include the steps to obtain the authorization token for invoking the target REST API, followed by the invocation of the API.

Obtaining the Authorization Token

1. Open Postman and click on “New”

2. In the pop-up dialog, select “HTTP Request”

3. Click on the “Authorization” tab in the request section under “Untitled Request”

4. Click on the “Type” drop-down and select “OAuth v2.0”.

5. In the right-hand section, scroll down to the sub-section titled “Configure New Token”, and enter the values as shown below:

1. Token Name: my-first-auth-token
2. Grant Type: Authorization Code
3. Callback URL: https://www.getpostman.com/oauth2/callback
4. Auth URL: https://example-auth.omni.manh.com/oauth/authorize
5. Access Token URL: https://example-auth.omni.manh.com/oauth/token
6. Client ID: <client_id> should be created by your Administrator
7. Client Secret: <client_secret> should be created by your Administrator
8. Scope: leave empty
9. State: leave empty
10. Client Authentication: Send as Basic Auth header

Click the “Get New Access Token” button to fetch the token.

6. Sign in with your username and password in the pop-up dialog. The pop-up may look different from the screenshot shown below depending on the Manhattan Active® application you are using.

7. Upon a successful login, Postman will display the access token in the UI, and give you an option to use it.

8. In the “Current Token” section of your REST API request, select my-first-auth-token from the list to make use of the token you obtained.

Invoking the REST API call

1. To invoke the API to get the details of your username, set the URL to the value shown below:

http://example.omni.manh.com/organization/api/organization/user/allDetails/userId/jerrythomas@example.com

Set the HTTP method to GET. The inputs will look like this:

Verify that the “Access Token” is set to my-first-auth-token in the “Current Token” section.

Click on the “Send” Button.

2. The API response in JSON format will be displayed in the section on the bottom

You can inspect the response content and headers by switching the response tabs.

Pro Tip

With the access token, you can also invoke the API using curl as a command line option instead of Postman:

curl -L -X GET  -H 'Authorization: Bearer eyJhbGciOiJSUzI1Ni...' 'http://example.omni.manh.com/organization/api/organization/user/allDetails/userId/jerrythomas@example.com'

Learn More

• Concept Guides
• Quick Starts

4 - Manhattan Active® API Reference

To learn more about calling an individual Manhattan Active® API, please see the API documentation in our solution sites:

• Manhattan Active Omni®
• Manhattan Active Supply Chain
• Manhattan Active Platform®