Creating a new app with the API

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

1. Check that your account’s license has the license for “Private apps (API)”
2. 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).
3. Go to Admin – Integrations – Private apps and the API.
4. Create a new app record. The app’s status will be first set to pending.
5. Contact Manu Online support via the “Contact us” form on our web site or email support@manuonline.com to get your app enabled.
6. 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 client id and secret. (See below for more details).
7. Code your own application using your choice of programming language.

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:

1. 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 below.)
   
   https://auth.manuonline.com/oauth/authorize?response_type=code&client_id={clientid}&redirect_uri={redirect_uri}&scope={scopes}
   
   
2. 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 URL must correct as per the app settings. Also, the user must have rights to the requested scopes on their user account.
   
   
3. 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. The validity time of an access token is 30 minutes and of a refresh token 2 years (730 days). To persist the connection over a longer period of time then the refresh token needs to be stored securely by the app. At the expiry of the refresh token, the user will need to log in to renew it (put it in your calendar!).
   
   
4. Include the access token in calls to the API as the Authorization header with the word “Bearer ” prefixed.
   
   
5. When the access token expires (after 30 minutes) or becomes invalid, use the refresh process to get another access token. This would normally be done without user intervention. The apps id and secret are needed to refresh the access token.
   
   

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 application that you create. Use a strong password for the user account.
3. Apply minimum user rights for the logic of your app. Apply minimum user rights 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 compromised.
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 itself. In OAuth2 terminology these are also referred to as “Scopes”.
4. Save the screen