Connecting to the APIs using tokens

Introduction

This tutorial explains how to connect to both e-conomic APIs (REST and SOAP) using Agreement Grant Tokens and App Secret Tokens, allowing app and integration partners to access data in e-conomic user agreements without having to store user credentials.

Notes and requirements
Permissions: The end-users permissions must match the permissions required by the app. See more on permissions and roles.
Administrators: Authorising an app requires you to be logged in as an end-user of the actual accounting agreement. It is not possible for admins to install apps on the end-users behalf.
Developers: Developer agreements do not contain accounting data. Authorising an app requires the end-user of an accounting agreement. See "Step 2" for links to create a free demo agreement.
Internal: Internal licenses are not currently supported.
 

Connecting in 3 steps

  • Sign up for a developer agreement
  • Create an app and tokens 
  • Connect to e-conomic end-user data via REST or SOAP

Step 1: Sign up for a developer agreement

Go to the Developer Network homepage and sign up for a developer agreement.
After registering you will receive an e-mail with login credentials for your new developer agreement.
 

Step 2: Create an app and tokens

Log into your e-conomic developer agreement and go to the Developer tab in the top left corner.

Select a fitting role and create a new app.

The e-conomic token authentication consists of two parts:

The App Secret Token is your apps own part of the composite key that let's you access accounting data.

The Agreement Grant Token is the second part of this composite key that gives you API access to accounting data.
To generate an AgreementGrantToken an end-user must visit your apps Request URL and grant your application access to their agreement.
 

Language of the request flow pages is set using the url parameter 'locale' that accepts either da-DK, sv-SE, nb-NO or en-US. Example: &locale=da-DK

To open the requestURL in a new window (_blank) you can use rel="noopener" on your <a> to ensure that the mother window remains yours at all times.

If you need a test environment, sign up for a free 14-day demo with test-data. Should you need it to live longer than the default trial period, please contact api@e-conomic.com.

 

Step 2A: Manual retrieval of Agreement Grant Token

Send the request URL to the end-user. When the end-users click the link, they are first asked to login to e-conomic  and then asked whether they want to grant your app access to their agreement data.

Please remember! Developer and Admin agreements do not contain accounting data. Please ensure you are logged in with an end-user agreement containing accounting data when generating the token.


After granting access to the app, end-users are presented with the AgreementGrantToken which they need to copy and send to you.
 

Step 2B: Automated retrieval of Agreement Grant Token

To automatically retrieve Agreement Grant Tokens, you need to set up a page on your webserver that grabs the token from the GET request URL parameters.
Upon granting your app access to their data the end-user is redirected to the redirectURL value with "token=SomeAgreementGrantToken" appended as URL parameter.

You must include a redirectURL parameter in the app link you supply to your end-users.
The redirect URL may contain additional information you need to identify a user on your end.
Important: redirectURL must be URL encoded.

Example:
You set up a page that picks up the token: https://www.example.com/tokensuccess.aspx
You'd like to keep track of the customer the token belongs to so your page also looks at the query parameter "userIdInMySystem=X".

For this example you're supplying a link to user "123" in the Acme Inc. app.
When user 123 has authenticated the app you would like him forwarded to this URL:
https://www.example.com/tokensuccess.aspx?userIdInMySystem=123

You first URL encode the URL: https%3A%2F%2Fwww.example.com%2Ftokensuccess.aspx%3FuserIdInMySystem%3D123

You then go to your developer agreement and find the RequestURL of your app:
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appPublicToken=xxxxxxx

You then add the redirect parameter (including your encoded URL) to instruct e-conomic to redirect the user upon succesfully authorising your app:
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appPublicToken=xxxxxxx&redirectUrl=https%3A%2F%2Fwww.example.com%2Ftokensuccess.aspx%3FuserIdInMySystem%3D123

When user 123 clicks the link above, he is asked to add the app to his agreement.
After granting access, the users browser is redirected to the redirectUrl value with the newly generated Agreement Grant Token appended.
The above results in the user being redirected to: https://www.example.com/tokensuccess.aspx?userIdInMySystem=123&token=theAgreementGrantToken

 

Step 3: Connect to e-conomic API

Once you have both an AppSecretToken and an AgreementGrantToken there are two ways of connecting to e-conomic:

Using REST

1. Add these three headers to your first request:
X-AppSecretToken: <TheAppSecretToken>
X-AgreementGrantToken: <TheAgreementGrantToken>
Content-Type: application/json

2. Issue a GET to https://restapi.e-conomic.com/self or https://restapi.e-conomic.com/customers and see what is returned.

Using SOAP

Using our SOAP service the method for token authentication is the ConnectWithToken method.
Please note that SOAP uses HTTP cookies to manage sessions. A successful authentication will include a Set-cookie HTTP header. Your framework/client should support cookies and include this in all requests.

Example:
ConnectWithToken(MyUsersAgreementGrantToken, MyAppSecretToken);

XML Schema:
<ConnectWithToken xmlns="http://e-conomic.com">
<token>string</token> //This is the Agreement Grant Token
<appToken>string</appToken> //This is the App Secret Token
</ConnectWithToken>
 

Need help?

We are ready to help you with your API questions at api@e-conomic.com