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.

Requisites for token auth (the guide will take you through this)
Developer agreement: Developer agreements are used to manage your apps, including token and market details. Step 1 in the guide below.
An app with proper permissions: The end-users must posess the permissions required by your app. Be sure to read how permissions and roles impact which entities your app can access. Step 2 guides you through this.
Accounting Data: Accounting data lives on an accounting agreement. Quick link to create a sandbox. See the FAQ at the bottom of this page for more info on sandboxes and trials. Step 3 in the guide below.
 

Note for administrators 
For administrators granting an app access requires you to first click "Administer" on the accounting agreement you want to generate a token for, before you can follow the Installation URL. More info here.

 

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 grant your app access via the "Installation URL" found in the Tokens section for your app (this results in an 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 "Installation URL" to the accounting user and ask them to return the token that is generated. This is an AgreementGrantToken.
Hint! - You can automate the process of collecting the AgreementGrantToken. See the advanced FAQ at the bottom of the page.

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. (Create sandbox)



 

Step 4: Connect to e-conomic APIs

Once you have both an AppSecretToken and an AgreementGrantToken you can connect to the two e-conomic APIs:

Connect to REST

Official documentation: https://restdocs.e-conomic.com/#tl-dr

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.

Note: We do not support URL parameter based auth. We only support request headers as stated above.

Connect to SOAP

Using our SOAP service the method for token authentication is ConnectWithToken.
Please note that SOAP uses HTTP cookies to manage sessions. Successful authentication will include a series of "Set-cookie" HTTP headers in the response. Your SOAP framework/client must support cookies and include the session cookies from responses in the subsequent call related to that session.
Call Disconnect() to destroy the session.

Example:
ConnectWithToken(AgreementGrantToken, AppSecretToken);

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 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 14-day trial period, please contact us and we'll be happy to help you with more time for testing.
 

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.
Required: You must first establish your own public endpoint (webpage) that picks up the token from the GET on our redirect of the users browser after grant succeeds.
 - 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 include the token as a URL parameter (token=xxx) in the redirect call to the address you just 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