​
Overview

When making requests to the maesn API you need to have the right request headers set, in order to authenticate your requests.

There are two primary authentication parts of the headers that we need to set:

These two are needed to authenticate your requests to the maesn API.

​
X-API-KEY header

For any request you make into the maesn API this is the header that authenticates yourself as a user of the maesn API. This is the API key that you get when you sign up for an account with maesn.

Please contact us at the following link to get started. We will get in touch with you to create an account and provide you with an API key.

​
X-ACCOUNT-KEY header

When trying to access your end user’s information in the target system, you will only be allowed to do so, if the end user went through the registration flow and authenticated to the target system, and you stored the X-ACCOUNT-KEY to use with these requests.

Every account key is unique to the end user and the target system, so an end user may have multiple of these depending on how many target systems they have authenticated to.

End user authentication is done through the /auth/:TARGET_SYSTEM endpoint.

curl --request GET \
  --url 'https://api.maesn.dev/auth/:TARGET_SYSTEM?callbackUrl=YOUR_CALLBACK_URL' \
  -H 'x-api-key: YOUR_API_KEY'

Replace :TARGET_SYSTEM with the target system you want to authenticate to. For example, to authenticate to Xero, replace :TARGET_SYSTEM with xero.

You can send the callback URL as a query parameter to the /auth/:TARGET_SYSTEM endpoint. This will redirect the user back to your system after the authentication flow is complete. You can also send a cancelCallbackUrl as a query parameter in cases where the user has to enter their API Key into our submission flow where they can cancel the flow. If these values are not provided, the user will be redirected with the default callback values that you provided when we contacted you for account creation.

In case of weclapp and xentral you have the option to use a query parameter tenantId to autopopulate the given field in the submission page.

This endpoint will give back a URL that you need to show to the user to authenticate to the target system.

At the end of the flow we redirect the user back into your system based on a redirect URL you provide when we contact you for account creation.

At this point you will receive an account token that you can use to make API calls on behalf of the user.

For target systems that doesn’t have an actual oAuth flow, there are two ways to generate an account key. Use the previously mentioned flow, and have a submission page shown to the user, or the /auth/accounts/:TARGET_SYSTEM endpoint can be used with a request body that contains the right values such as apiKey. The second endpoint is appropriate when authenticating an end user without any UI interaction. For example, if you want to create the UI with your own user experience or have already collected all the client credentials at an earlier stage. You can check out all the available target systems at the Create account endpoint.

​
Interactive Authentication Flow

In some supported systems, users must select a specific environment or company to complete their integration.

You can either:

  • Pass these values manually as query parameters in each API request
  • Or use the Interactive Authentication Flow

When environmentSelection=true is set in the query, the user is redirected to a selection page where they choose their environment or company. Once selected, those values are stored for future requests — so you don’t need to send them again.

Using the Interactive Authentication Flow ensures a consistent authentication experience across all systems — whether or not the end user needs to make a selection. This simplifies your implementation by removing the need to build custom selection steps into your own flow.

If you use the Interactive Authentication Flow but also send the environment or company parameters manually, those values will overwrite the ones stored for the user.

This flow also supports callbackUrl and cancelCallbackUrl, which define where the user is redirected after completing or cancelling the flow.

You can also customize the UI of the selection page to match your own branding and provide a seamless user experience.

Note: The Interactive Authentication Flow is only available for the following target systems:

  • businesscentral
  • exact-nl
  • moneybird
  • sage-active-de
  • sage-active-es
  • sage-active-fr
  • twinfield
  • datev-uo
  • datev-rewe
  • datev-uo-longtoken
  • datev-rewe-longtoken

Please ensure that the companyId query parameter is not set when using interactive authentication with DATEV long tokens, as it may prevent the flow from working correctly.

​
Headless Authentication flow

Some of the supported systems have an API key approach instead of the oAuth flow. In these cases maesn provides a UI page where the user can enter their API key and authenticate to the target system. We offer the flexibility to bypass this UI page by implementing our Headless Authentication flow, which returns the account key directly in the API response. There is a POST /auth/accounts/:TARGET_SYSTEM endpoint that can be used to authenticate the user without using the UI page. This endpoint requires a body with all the required fields, and will send back the account key in the response.

Note: This flow is only available for the following target systems:

  • sevdesk
  • holded
  • xentral
  • weclapp
  • buchhaltungsbutler-api

​
Page Design for Authentication pages

The authentication pages provided by maesn can be customized to match your brand’s look and feel. At the moment there is no way for you to change it, if you provide us the following values we can add them for you:

  • Background color code
  • Submit Button color code
  • Text color code
  • Input field background color code
  • SVG logo
  • Cancel Button color code
  • Error Text color