Browse Documentation
Authentication

Authentication

To interact with Accounteer account, you need to authenticate yourself. Authentication is done by using OAuth, this is the only authentication mechanism available in the Accounteer API. To start with OAuth, you need to register your application, download the client ID and secret and exchange these ids for access tokens which you can use to access our API.


Registration of your Application

Before you can use OAuth2 in our API, you will need to register your Application with Accounteer. Registration allows us to know which app is making a request to authenticate and who the owner of the app is.

To register a new app you can visit our developer page and click on login, you will be redirected to our main app where you can single sign-on and be redirected back to the developer app where you can proceed to create your app.

After your Registration, you will be given Client ID and Client Secret. You will use these tokens to identify your application when requesting access for users.


Scopes

Right now Accounteer allows the authenticated app to have access to the following scopes

  •     Account
    Invoices
    Offers
    Purchases
    Financial Accounts
    Items
    Contacts
    Taxes
    Organisation


  • Authentication

    In order to access the API in behave of a user, you need to get an.access token This token will give you access to the resource belonging to the user in the given scope. During the authentication of your user, Accounteer creates a special API user with access to the administration. All actions performed by your application will be named based on the application you registered.
  • Authenticating a user consists of the following steps, as prescribed by the OAuth 2.0 protocol:
  • 1. In your application, obtain a request token and authorise URL using an Authorization Request:
  • You can place a form on your app to request for Authentication code by or you can also leverage the web browser URL to obtain an Authentication code since it's an HTTP GET request. 
curl -vv \ 'https://app.accounteer.com/oauth/v2/auth?client_id=26766825788095593&redirect_uri=https://accounteer.com&response_type=code'
  • 2 . The response of the HTTP request contains a Location header and HTML content pointing towards an authorized URL. Redirect your user to this URL. Accounteer present the user with a login screen, checks all credentials (user should be the owner of the administration) and presents the user with an authorization screen as shown below:

  • 3. When the user authorizes your application, Accounteer redirects the user to you providedredirect URI in the first step. If you use the redirect url:https://accounteer.com URI to indicate that the redirect URI is Out-of-Band, the user will not be redirected. Instead, the code is displayed in the web browser.
  • eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJuYmYiOjE0ODgyMDM2ODgsImlhdCI6MTQ4ODIwMzY4OCwiZXhwIjoxNDg4MjA3Mjg4LCJidXNpbmVzcyI6MjIsInVzZXIiOjcsImNsaWVudCI6Mn0.ZlPsR3gBTKUgpILD1Bkjf1hiMBqNzWnw9forou_vSY2fd23ogf41JJBAX4IZGHcY_nadI18jwk9wk6EiO-LlSA

4. With the Authentication Code appended to the,redirect URI you can exchange it for an access token with an Access Token Request:

curl -vv \  -X GET \  -d "client_id=2166825788095593&client_secret=ndzjmzotq0mzfiodjhythhnwjiyzkymzlmmjg2zdcxowe4mmq3mzu0nja0&code=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzxMiJ9.eyJuYmYiOjE0ODgyMDc4NjEsImlhdCI6MTQ4ODIwNzg2MSwhwIjoxNDg4MjExNDYxLCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.64p3eQDfOJX48ws9XWF2fxFItJVLD1ORJOQk8DXjqLUq29wf2snXvkeQddgKq7gQ4AIxm_fbLb1tL3OewDQ&redirect_uri=https://accounteer.com&grant_type=authorization_code"
\ 
https://app.accounteer.com/oauth/v2/token

You can run the code above on the terminal to get your access token and refresh token or you can also issue the request in your web browser like below.

https://app.accounteer.com/oauth/v2/token?client_id=2_3166825788095593&client_secret=ndzjmzy1otq0iodjhythhnwjiyzkymzlmmjg2zdcxowe4mmq3mzu0nja0&code=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJuYmYiOjE0ODgyMDc4NjEsImI6MTQ4ODIwNzg2MSwiZXhwIjoxNDg4MjExNDYxLCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.64p3eQDfOJX48ws9XWF2fxFbXfItJVLD1ORJOQk8DXjqLUq29wf2snXvkeQddgKq7gQ4AIxm_fbLbOewDQ&redirect_uri=https://accounteer.com&grant_type=authorization_c

The Authentication code will expire within 1 hour after it's issued, so you will need to use it to request for access token within that time or you can authorise your app again to obtain a new Authorization Code. And if all parameters provided were correct you should receive your access and refresh token like below.

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ.JleHAiOjE0OTU4OTM5MjUsIm5iZiI6MTQ4ODIwNzkyNSwiaWF0IjoxNDg4MjA3OTI1LCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.C0gwdXg6P9nE1tA5icoluKHueEo1eCFi0qmgfkbWqHM4IIzGqeKpP6q1C_A-C7wNjz9KRZut61xBM-5A",
 "expires_in": 3600,
 "token_type": "bearer",
 "scope": null,
 "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUJ9.eyJleHAiOjE0OTU4OTM5MjUsIm5iZiI6MTQ4ODIwNzkyNSwiaWF0IjoxNDg4MjA3OTI1LCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.C0gwdXg6P9nE1tA5icoluKHueEo1eCFi0qmgfkbWqHMPBoSciGqeKpP6q1C_A-C7wNjz9KRZut61xBM-5A"
}

If the Authorization code has expired you will receive the below response

{"error": "invalid_grant","error_description": "The authorization code has expired"}
  • 5. The response containsAccess token you can use to connect with the API. The canRefresh token be used to retrieve a new access token in case the access token can expire. In that case, an isexpires_in given. Both the access token and the refresh token should be persisted to be used for future requests.

  • 6. To refresh an access token with the refresh token, call the token URL:

  • https://app.accounteer.com/oauth/v2/token?client_id=2_3166825788095593&client_secret=ndzjmzy1otq0mzfiodjhythhnwjiyzky2zdcxowe4mmq3mzu0nja0&refresh_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJuYmYiOjE0ODgyMDc4NjEsImlMTQ4ODIwNzg2MSwiZXhwIjDg4MjExNDYxLCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbn9.64p3eQDfOJX48ws9XWF2fxFbXfItJVLD1ORJOQk8DXjqLUq29wf2snXvkeQddgKq7gQ4AIxm_fbLb1tL3OewDQ&redirect_uri=https://accounteer.com&grant_type=refresh_token

if the refresh token has not expired you should be greeted with a JSON response containing your new access token and refresh token and see a response like below

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJiJ9.eyJleHAiOjE1MDM4NDQzMzIsIm5iZiI6MTQ4ODIwOTUzMiwiaWF0IjoxNDg4MjA5NTMyLCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.kTVtfmMLOEBsBxKSeJupQ2RP0wo6kPyqWFxQvcuU5nk7hRKlwxZPurK0IlMXrWxa8ktab0Yquc5j9s1w",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOixMiJ9.eyJleHAiOjE1MDM4NDQzMzIsIm5iZiI6MTQ4ODIwOTUzMiwiaWF0IjoxNDg4MjA5NTMyLCJidXNpbmVzcyI6NjIsInVzZXIiOjEwLCJjbGllbnQiOjJ9.kTVtfmMLOEBsBxKSeJupQ2RP0wo6kPyqWFxQvcuU5nk7hRKlw-mcurK0IlMXrWxa8ktab0Yquc5j9s1w"
}

Once your request for a new access token is successful you are fully equipped and can go ahead and use this access token to request for resources on Accounteer.