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 actively administering the accounting agreement you want to generate a token for. Read more about admins and tokens.
Developers: Developer agreements do not contain accounting data. Authorising an app requires the end-user of an accounting agreement or an administrator. See the FAQ at the bottom of this page for links to create a free demo agreement.
 

The quick guide
 

  • Sign up for a free developer agreement
  • Sign in and create your first app via the 'Apps' tab (save AppSecretToken in a safe place)
  • An accounting user must accept the app via RequestURL (results in the AgreementGrantToken)
  • Connect to e-conomic accounting data via REST or SOAP using the two tokens.

The full guide
 

Step 1: Sign up for a free developer agreement

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

Step 2: Create your app

Log into your e-conomic developer agreement and go to the Developer tab in the top left corner.
Click "New app".
Give it a descriptive name, select a fitting role and create the new app.
You can now add the first half, the AppSecretToken, to your authentication headers (REST) or parameters (SOAP).
 

Step 3: Gain access to accounting data

Send your apps requestURL to the accounting agreement end-user and ask them to return the token once generated.
Please note! Please ensure you are logged in with an end-user agreement containing accounting data when generating the token. If you're generating it locally, logout of your developer agreement first.



 

Step 4: 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. Successful authentication will include a "set-cookie" HTTP header in the response. Your SOAP framework/client must support cookies and include these in all requests made related to the session.

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>


 

Advanced info and FAQ

 

What are the tokens?

e-conomic token authentication consists of two parts:
1: The App Secret Token is your apps own part of the combined key. This can be used in combination with one or more AgreementGrantTokens.
2: The Agreement Grant Token is the second part of token authentication that gives you API access to the accounting data of that specific e-conomic agreement.
 

RequestURL options

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.
 

Sandbox / demo / test environment

If you need a test environment, sign up for either a free 14-day trial with demo-data or a blank trial.
Should you need it to live longer than the default trial period, please contact us and we'll be happy to help you get started.
 

Automating retrieval of AgreementGrantToken

There are two options available for automating the AgreementGrantToken retrieval.

1: Using our PartnerAPI to retrieve and keep up-to-date on accounting agreement access.


2: Adding a redirectURL parameter to the requestURL of your app. 
*Requires a public endpoint (webpage) that picks up the token from the GET request URL.
Upon a user granting your app access to their accounting data the browser will redirect to the redirectURL you supplied and have "token=SomeAgreementGrantToken" appended as a URL parameter.
Important: The entire string you include in the value for the redirectUrl must be URL encoded.

Example:
You've set up a page that picks up the token on: https://www.example.com/tokensuccess.aspx
Optional: We fully support adding any custom parameters to the redirectURL value as long as these are also URL encoded.

First you need the RequestURL of the app:
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appPublicToken=xxxxxxx

You then add the redirect parameter and value (value must be URL-encoded):
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appPublicToken=xxxxxxx&redirecturl=https%3A%2F%2Fwww.example.com%2Ftokensuccess.aspx

The user clicks the link above and when granting your app access, the browser is instantly redirected to the redirectUrl with the parameter "token" appended and the AgreementGrantToken as value.
Following the example the user is redirected to: https://www.example.com/tokensuccess.aspx?token=aNewAgreementGrantToken

Please ensure that you give the user proper feedback on the success of the operation.

An example of adding a requestURL that includes your own parameters
In this case I'd like to provide personalized links inside my system and have the user ID included as a parameter when I get the token. I conjure up "UserInMySystem=123" for this example.
When properly encoded and added to the requestURL I then end up with the link: 
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appPublicToken=xxxxxxx&redirectUrl=https%3A%2F%2Fwww.example.com%2Ftokensuccess.aspx%3FuserIdInMySystem%3D123
As long you remember to URL-encode the value of the redirecturl you have free hands.
 

URL/Query string basics
A query string can only hold one question mark "?" which tells the browser that the first parameter are coming. Subsequent parameters must be added using ampersand "&".
As long as your redirectURL is encoded correctly you should only have to verify that it is valid before you encode it and add it to the requestURL.
Wikipedia article about the query string.
Eric Meyers URL encoder/decoder
 

Need help?

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