Connecting to the APIs using 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 or OpenAPI

Official documentation: 
REST: https://restdocs.e-conomic.com/ 
OpenAPI: https://apis.e-conomic.com/ 

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.
Do note: We do not support URL parameter based auth. We only support request headers as stated above.

Connect to SOAP (Being deprecated - end of life 31.12.2023)

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 installation 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.

Note: If you're linking from another browser-window do set target="blank" and rel="noopener noreferrer" on your link.