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 (SuperUser, ignore modules part, store AppSecretToken in a safe place)
  • An accounting user must "install" the app via installationURL found in the Tokens section for the app (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 ensure you are on the Apps tab in the top left corner.
- Click "New app".
- Give it a descriptive name, select a fitting role (e.g. SuperUser for tests) and create the new app.
Note: The "Required modules" is ONLY for apps headed to e-conomic market. You may ignore this for an app you will not be publishing.
- You can now add the first half, the AppSecretToken, to your authentication headers (REST) or parameters (SOAP).
Note: Keep your AppSecretToken in a safe place. It will not be displayed again (you can always generate a new one by clicking 'reset').
- Now click on the "tokens" button to get the installationURL for your app.
 

Step 3: Gain access to accounting data

Send your apps installationURL to the accounting agreement end-user and ask them to return the token once generated.
Do note! Please ensure you are logged in with an end-user agreement containing accounting data when generating the token. If you're generating it for a sandbox accounting agreement, log out 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 is a combined key that consists of two parts:
1: The App Secret Token is your (as developer) 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 the e-conomic user that granted your app access.
 

installationURL options

Language of the installaiton 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 installationURL 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 redirect to the installationURL of your app.
*You must first establish your own public endpoint (webpage) that picks up the token from the GET installationURL.
 - Login to your developer agreement and click on the "tokens" button
 - Fill in the redirect URL box
 - Now the installationURL is updated with your redirect path and parameters.
 - When the user has accepted the app we will append the token as URL parameter "token=xxx" to the redirect you set up.

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

Need help?

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