Learn how to authenticate your requests to the maesn API
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.
: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.
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
/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