Authentication

Authentication

All requests to Neto’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 Neto 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 Neto 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 Neto 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: Neto’s API which a client can use to read and update data in the Control Panel.
  • User: A merchant that holds a Neto subscription. The user provides access to a client.

Process

Neto 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 Neto 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 Neto application authorisation page.
  3. Merchant logs into their Neto 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. Neto 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 Neto API using the obtained access token and store domain.
  9. Neto responds with resources from the merchant’s account.

Obtain Credentials from Neto

You must be an approved add-on developer to obtain credentials from Neto. 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 Neto team.


Request Authorisation

When a merchant installs your application from the control panel they will be redirected to the Neto 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 Neto 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 Neto 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://{neto app portal domain}/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 Neto team. {client_secret}: Your application’s client secret, obtained from the Neto 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 Neto 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.