Authentication

All requests to Maropost Commerce Cloud's API must be authenticated regardless of whether you’re creating a new add-on or developing a custom integration. There are two methods of authenticating with a Maropost Commerce Cloud Store:

  • API Key (Basic)
  • OAuth

The type you use will depend on whether you’re developing an add-on (public) or a custom integration. Add-ons that will be available in the add-on store must use OAuth to authenticate. Custom add-ons or development can use an API key.

Authenticate with an API Key

There are two types of API keys that you can use to authenticate your add-on with the Maropost Commerce Cloud control panel:

  • User Based API Key (recommended)
  • Global API Key

User Based API Key

A user based API key is tied directly to the access of a staff user in a merchant’s Control Panel. The access provided by one of these keys can be limited to certain interactions with the API by creating a user permission group.

This method of creating API keys is recommended as it gives a merchant more granular control over the data that an add-on has access to as well as the ability to disable access per add-on.

You can obtain a user based API key by creating a new staff user and generating an API key on their account.

Global API Key

In every Maropost Commerce Cloud Control Panel there is a single global API key which can interact with all the data that’s available in the API. It is not recommended to use this type of key as it’s not possible to limit the access it provides and in order to revoke access you need to reset the key which others might be using. In general, this type of API key should only be used for things such as testing, experimenting and debugging.

You can obtain your global API key in the control panel by going to Settings & tools > All settings & tools > API.

Usage

An API key must be supplied in the NETOAPI_KEY header of each request.

Authenticate with OAuth

Public add-ons that are listed in the add-on store in the control panel must authenticate using OAuth2.0 to get access to a merchant’s data.

Terminology

If you’re not already familiar with the OAuth2.0 specification, you can read more information about it here. You should be familiar with the following key terms:

  • Client: Any add-on that wants to access a merchant’s data. A merchant must grant permission to a client before it can access anything.
  • API: Maropost Commerce Cloud's API which a client can use to read and update data in the Control Panel.
  • User: A merchant that holds a Maropost Commerce Cloud subscription. The user provides access to a client.

Process

Maropost Commerce Cloud uses OAuth 2.0’s authorisation code grant flow to issue access tokens on behalf of users. The OAuth flow can be initiated from the Maropost Commerce Cloud control panel or directly from your application interface (if applicable). If your add-on requires that the user first have an account in your application you may choose to only allow the add-on to be initiated from your application interface.

The ideal workflow is as follows:

  1. Merchant requests to install the add-on.
  2. Merchant is redirected to the Maropost Commerce Cloud application authorisation page.
  3. Merchant logs into their Maropost Commerce Cloud account.
  4. Merchant is redirected to your add-on’s callback URL.
  5. Your application requests an access token for the merchant’s account.
  6. Maropost Commerce Cloud provides an access token and the store domain for the merchant.
  7. Your application notifies the merchant that they have successfully authorised the add-on.
  8. Your application makes requests to the Maropost Commerce Cloud API using the obtained access token and store domain.
  9. Maropost Commerce Cloud responds with resources from the merchant’s account.

Obtain Credentials from Maropost Commerce Cloud Cloud

You must be an approved add-on developer to obtain credentials from Maropost Commerce Cloud. See here for information regarding add-ons and how to register your interest in developing one. API scopes are defined when your credentials are provisioned by the Maropost Commerce Cloud team.

Request Authorisation

When a merchant installs your application from the control panel they will be redirected to the Maropost Commerce Cloud application authorisation page:

To initiate the flow yourself and display this page, you will need to redirect the user to the following URL:

https://apps.getneto.com/oauth/v2/auth?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&store_domain={store_domain}&state={nonce}

{client_id}: Your application’s client ID, obtained from the Maropost Commerce Cloud team. {redirect_uri}: One of your application’s registered install endpoints. {store_domain}: The store domain of the merchant's account you want authorization for. {nonce}: A random value unique to each request that you should validate before requesting an access token. This is an optional parameter but is recommended for the security of your application.

Request Access Token

After the user has successfully authenticated on the Maropost Commerce Cloud application authorization page they will be redirected to your application as provided in redirect_uri. Your server can then exchange the provided access code for an access token by sending a request to the token endpoint:

https://apps.getneto.com/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&grant_type=authorization_code&code={access_code}

{client_id}: Your application’s client ID, obtained from the Maropost Commerce Cloud team. {client_secret}: Your application’s client secret, obtained from the Maropost Commerce Cloud team. {redirect_uri}: The URI that was supplied in the initial code request {access_code}: The authorization code that was returned from the successful authorization request

If the request is successful you will receive a response with an access token, the merchant’s store domain, and additional information:

{
    "scope": "api user address",
    "store_id": "{store_id}",
    "store_domain": "www.paulspooltoys.com.au",
    "store_timezone": "Australia/Brisbane",
    "access_token": "{access_token}",
    "user": {
        "id": "{user_id}",
        "first_name": "Ryan",
        "last_name": "Murtagh",
        "email": "{user_email}”
    },
    "billing_address": {
        "street1": "123 Sample St",
        "street2": "Level 3",
        "city": "Brisbane",
        "state": "Queensland",
        "post_code": "4000",
        "country_name": "Australia",
        "country_code": "AU"
    }
}

Making Authenticated Requests

Now that you have a store domain and access token, you can make authenticated requests to the Maropost Commerce Cloud API: https://www.paulspooltoys.com.au/do/WS/NetoAPI

You will need to supply the following headers:

  • X_ACCESS_KEY: Your application’s client ID
  • X_SECRET_KEY: The access token returned from the token response

Was this article useful?

Be notified when this page is updated. Optional.