Private Apps

Private apps are your own applications that connect to your data using the Manu Online API.

Introduction

To create a private app, you will need programming skills, a programming environment suitable for creating internet base Restful application calls. Manu Online API uses the industry standard OAuth2 for authentication. You will need to be familiar with the concepts of OAuth2 to successfully create a program.

We support Swagger API documentation. You can browse and try out our API with your own data by going to https://api.manuonline.com/swagger/ui/index. You do not need a private app to browse our Swagger pages but you do need a user with API rights and to have the Public integrations extension licensed in your system.

It is also possible to create webhooks. These are used to trigger actions in your application as a result of a Manu Online user doing something in the system, for instance saving partner data or activating a sales order. Webhooks are associated with private apps for security reasons. Even if you only use webhooks then you will still need to register a private app even if you don't create code for it.

IMPORTANT: the various API keys and logins issued as part of private apps will allow a developer to gain access to read and modify your corporate data. Treat keys as confidential information. Store them securely and do not send them by unsecured email.

Licensing

To use private apps, you need to license the "Private apps (API)" extension. Depending on the Edition of Manu Online that you are using and our current pricing policies this extension there may or may not be a charge for this extension or you may need to upgrade your Manu Online account to access it.

How to create (i.e. register) a private app

• Check that you account's license has the license for "Private apps (API)"
• Create a user and give the user API rights according to minimum rights. You will need a unique email for this. Alternatively give the rights to an existing user (but this is not recommended).
• Go to Admin - Integrations - Private apps and the API.
• Create a new app record. The app's status will be first set to pending.
• Contact Manu Online support via the "Contact us" form on our web site or email support@manuonline.com to get your app enabled.
• When it is enabled, go back to app listing on the integrations screen, click edit to see the full details and OAuth2 parameters. Fill in the needed parameters and pickup the cliend id and secret. (See below for more details).
• Code your own application using your choice of programming language.

Preview

Setting and retrieving your OAuth2 parameters

Once your app has been approved then the keys will be available. Go back to the private apps screen and click the Edit button next your app.

• Internal comments and application Url are for your own information
• Set one, two or three Manu Online accounts that can be used by this app. The account id can be seen from the Integrations screen.
• Set one, two or three approved redirect Url's for the OAuth process.
• Copy your cliend id and secret to your own code in a secure manner. Press the Regenerate button to get a visible client secret. The second secret is optional so that that you can run your app for the time it takes you to regenerate a key but note that web hooks client verification is based only on the first key only.

Implementing OAuth2

In addition to the above redirect url's and client credentials, you will need to use the following OAuth2 settings. You will need to code the logic of getting and refreshing the tokens. We follow industry standards for OAuth2. There are a lot of public resources and training materials for OAuth2 on the internet. One example would be https://www.oauth.com/oauth2-servers/accessing-data/​

• Authorization URL: https://auth.manuonline.com/oauth/authorize
• Access token request: https://auth.manuonline.com/oauth/token
• Refresh token request: https://auth.manuonline.com/oauth/token

Access tokens are valid for 30 minutes. Refresh tokens are valid for two years.

In summary the process is as follows:

• The app code should redirect the user to the Manu Online authentication server with the following url (replace placeholders {clientid},{redirect_uri}, {scopes} with real values. Multiple scopes can be included in a comma delimited list. (The list of valid scopes can be seen from the user screen. Screen shot is above.)

https://auth.manuonline.com/oauth/authorize?response_type=code&client_id={clientid}&redirect_uri={redirect_uri}&scope={scopes}

• The user will be prompted to enter his Manu Online user name and password, as in the screen shot higher up in this document. After successfully authenticating the user presses the Grant button and is redirect users back to their redirect_uri with an authorisation code. The client id, key and redirect uri must correct as per the app settings. Also the user must have rights to the requested scopes on their user account.
• The application code needs to contact the authentication server with the authorisation code, client_id and client_secret (url and form data supported) to obtain an access token and a refresh token . To persist the connection over a longer period of time then the refresh token needs to be stored securely by the app.
• Include the access token in calls to the API as the Authorization header with the word "Bearer " prefixed.
• When the access token expires or becomes invalid, use the refresh process to get another access token. This would normally be done without user intervention.

Security recommendations

1. If you are not using the API keep the licenses for both Private App and Public Integrations switched off in your Licensing section
2. Create and use a separate user name in each appiication that you create. Use a strong password for the user account.
3. Apply minimum user rights for the logic of your app. Apply mininimum user rights in for Manu Online for these users. e.g. Partner read only.
4. Do not store or transmit your Client Secrets in an insecure manner.
5. Regenerate your client secret if there is a risk that it has been comprimised.
6. Note that IP filtering of the user account does not apply to API users.

Setting user rights for the API

1. Create a new user (recommended, although you can give rights to an existing user.
2. Go to Admin - Users and select the user
3. On the API tab select the appropriate rights that your app will need. For all rights you can use the API_All right by iteself. In OAuth2 terminology these are also referred to as "Scopes".
4. Save the screen

Testing your user with the API documentation

1. Ensure that you have "Public integrations" licensed on your system. (By removing the license to public integrations you can prevent access to all users of your account.)
2. Go to https://api.manuonline.com/swagger/ui/index to see the testable documentation. (Note that this page needs a "modern" browser and legacy Internet Explorer is not supported.)
3. Optionally enter one or a comma delimited list of scopes.
4. Press "Connect". You will get a screen to enter your user name and password. If you have access to more than one Manu Online account, you will be prompted to choose the appropriate account. On successful authentication you will be asked to "Grant" access to the account indicated. The popup window will close.
5. Choose an end point and press Try it out! Data should be returned. The endpoint "/me" is a good place to test. It will just return your authenticated user name. You will also see the curl code that can be used.

Testing the API interface with the Postman utility

Postman is a utility that is widely used in the industry for working with API's. Their smallest version is available for free.

Follow Postman's instructions to set up a new endpoint. Select OAuth2 as the authentication method. Copy the Postman Callback URL back to your app settings in Manu Online.

This is how the OAuth2 set up screen looks for Manu Online in the Postman API test utility.

Notice that Manu api allows only "authorization code" grant type.

After you request the token, you can see that Postman has received the Refresh token and used it to get the Access token:

When sending refresh token notice that it is valid for only one access token retrieve. When receiving access token Manu Api returns also new refresh token. Store new refresh token for next access token retrieve.

Refresh token is sent in this way:

Here you can see the Access Token in Postman's header:

Webhooks

Webhooks are data transfers triggered by an action by a user in Manu Online. They send data out from the system to the address address specified. The server on the receiving end is often called the "listener". While it is also possible to "get" data from your Manu Online account by using the API, webhooks have a huge advantage that if there is a transmission error or business logic error on the listner, then the user will get immediate feedback and can try again.

Read more about web hooks from this page.