Connecting to the APIs using tokens
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.
Note: If you need a test environment, sign up for a trial or demo agreement in the country of your primary user: Denmark Sweden Norway. Should you need it to live longer than the default trial period, please contact firstname.lastname@example.org.
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.
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:
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:
You then add the redirect parameter (including your encoded URL) to instruct e-conomic to redirect the user upon succesfully authorising your app:
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:
1. Add these three headers to your first request:
2. Issue a GET to https://restapi.e-conomic.com/self or https://restapi.e-conomic.com/customers and see what is returned.
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.
<token>string</token> //This is the Agreement Grant Token
<appToken>string</appToken> //This is the App Secret Token
One last thing: Make your developer agreement permanent
Per default your newly created developer agreement only lives for 90 days. In order to make your developer agreement permanent please send the developer agreement number and a short description of your service to email@example.com asking them to make your developer agreement permanent.