API Authentication

Authentication and authorization with Procountor API

Accessing Procountor API

Accessing Procountor API requires authenticating and authorization. Users need to prove with an access token they have a permission to use the API. Procountor API adapts the OAuth 2.0 flow as a method for authorization.

The instructions on this page cover the essentials required for implementing authorization with Procountor API. For further information about OAuth 2.0, refer to the official website.

Prerequisites for testing access

The following information is required for obtaining a grant to use the API for testing purposes. This information can be obtained by submitting a request for a testing environment.

  • Client ID
  • Client secret
  • Redirect URI

In addition to the information above any user wishing to log in needs to have the following information at hand in order to complete the login flow.

  • Username
  • Password
  • Company Name

Redirect URI

The redirect URI indicates a location where the user's browser is redirected after authenticating on Procountor API login page in a fully implemented authorization process. If you do not specify a value for the redirect URI in your testing environment request, we will assign you a placeholder value. In any case, providing the value is mandatory in the authorization process described below.

Each API client has exactly one redirect URI. The value is stored with API client details by Procountor and cannot be modified by the user. To change the redirect URI after receiving your testing environment drop us a line and state your client ID and the new redirect URI.

User credentials for testing

When you receive a testing environment you will also be given an initial user account connected to a new company. You can use this information to log in to the testing server UI as well as the API. You can create more user accounts using the testing server UI.

Authentication methods

The Procountor API offers two different OAuth 2.0 flows for this: the authorization code flow and the client credentials flow. The authorization code flow is best suited for interactive applications like web and mobile apps. The client credentials flow is best suited for machine-to-machine integrations, like reporting or monitoring platforms.

This page contains the instructions on how to log in and use the API with the authorization code flow. The instructions for using the client credentials flow can be found from the M2M Authentication page.

Machine to machine authentication

Legacy integrations

For legacy integrations we also offer an alternate authentication flow which is descibed here.
This flow is considered deprecated and will be removed in April 2021 update.
You should migrate to using the client credentials flow before then.

Authorization Code Grant flow

Before making actual requests to Procountor API endpoints, the user first needs to obtain an access token. Getting an access token follows the OAuth 2.0 Authorization Code Grant flow. The first step in getting an access token is to obtain an authorization code. This code is then swapped for an access token.

Step 1: Obtaining authorization code

Direct user to API login page

To obtain the authorization code the user needs to be directed to Procountor API login page:

GET https://api.procountor.com/login?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<state> HTTP/1.1

The client_id and redirect_uri parameters given in the URL are integration specific and given to you when you request a testing environment. The state parameter is optional, implementation specific, and will be returned with the authorization code. All parameters need to be URL encoded.

User performs login

The user is shown a login dialog, where they need to enter their username and password in order to log in. After entering correct credentials the user is directed to another dialog, where they must select a company they want to authorize access to. Note that the login page requires JavaScript in order to function correctly.

API login dialog API company dialog

User is forwarded to redirect URI

After succesful login the user is forwarded to the integration specific redirect URI:

HTTP/1.1 302 Found
Location: <redirect_uri>?code=<authorization_code>&state=<state>&expires_in=300

The value of the state parameter matches the value given to the login page and can be used e.g. for matching purposes. The code parameter is the authorization code which will be used in the next step. This is a single use code valid for five minutes.

Step 2: Trading code for access token

Before using any of the API endpoints the authorization code needs to be exchanged for an access token. This is done by sending a POST request our OAuth token endpoint from your application with the following application/x-www-form-urlencoded data:

POST https://api.procountor.com/api/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=<client_id>&
client_secret=<client_secret>&
redirect_uri=<redirect_uri>&
code=<authorization_code>

The client_id, client_secret, and redirect_uri parameters are integration specific and given to you when you request a testing environment. The code parameter is the single use authorization code from the previous step. As a response to this request you will receive a JSON document with access and refresh tokens:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS10ZXN0LnByb2NvdW50b3IuY29tIiwiYXVkIjoiY2xpZW50X2lkIiwic3ViIjoyNjUzNSwiY2lkIjoxNDE1OSwianRpIjoiN2Q0NDQ4NDAtOWRjMC0xMWQxLWIyNDUtNWZmZGNlNzRmYWQyIiwiYXV0aF90aW1lIjoxNjA3OTYyNDc5LCJpYXQiOjE2MDc5NjI0ODAsImV4cCI6MTYwNzk2NjA4MH0.GFBGknrx39Jm2UbUOrtV6X0R3pzaldmXa-AQhYVQ5JE",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS10ZXN0LnByb2NvdW50b3IuY29tIiwiYXVkIjoiY2xpZW50X2lkIiwic3ViIjoyNjUzNSwiY2lkIjoxNDE1OSwianRpIjoiN2Q0NDQ4NDAtOWRjMC0xMWQxLWIyNDUtNWZmZGNlNzRmYWQyIiwiYXV0aF90aW1lIjoxNjA3OTYyNDc5LCJpYXQiOjE2MDc5NjI0ODAsImV4cCI6MTYyMzY4NzI4MH0.DCaErPNgefZDa1hZF4t1L8pp4Dw_RiH-TUCkbUVqIRA",
  "expires_in": 3600
}

The access token is valid for one hour and the refresh token can be used to get a new access token after the previous one expires. More information about these tokens can be found below.

Authentication tokens

The authentication tokens used by Procountor API are in JWT format. The tokens come in two varieties: access tokens, which can be used to call API endpoints, and refresh tokens, which can be used to refresh an access token. The tokens identify a logged in user, and the company they have logged in to. The tokens are signed using HMAC SHA-256 algorithm.

Note that while the access token can be passed to client-side implementation if necessary, the refresh token should be kept secret.

Common information, shared by both tokens, looks as follows:

{
  "iss": "https://api-test.procountor.com",
  "aud": "client_id",
  "sub": 26535,
  "cid": 14159,
  "jti": "7d444840-9dc0-11d1-b245-5ffdce74fad2",
  "auth_time": 1607962479,
  "iat": 1607962480,
  "exp": 1607966080
}

Where the contents of the fields are:

  • iss: issuer - principal that issued the token
  • aud: audience - your API client ID
  • sub: subject - user ID
  • cid: company ID
  • jti: JWT ID - random sequence unique for the token
  • auth_time: time when the authentication occurred
  • iat: issued at - time when the token was issued
  • exp: expiration time - time when the token expires

Access token

Access tokens are used to authorize calls to API endpoints. An access token must be supplied with every request to the API unless otherwise stated. The access token must be included as a bearer token in the Authorization header of your requests:

GET https://api.procountor.com/api/sessioninfo HTTP/1.1
Authorization: Bearer <access token>

An access token is valid for one hour (3600 seconds) from the time of issuing. The access token can also be invalidated with a POST request to the /logout endpoint:

POST https://api.procountor.com/logout HTTP/1.1
Authorization: Bearer <access token>

Other situations where an access token will be invalidated are if the user changes their password in Procountor, or the user is removed from the company the access token is connected to.

Refresh token

Refresh tokens can be used to retrieve a new access token when one expires. This is done by sending a POST requst to the OAuth token endpoint with the following contents:

POST https://api.procountor.com/api/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
client_id=<client_id>&
client_secret=<client_secret>&
refresh_token=<refresh_token>

Here the client_id and client_secret parameters are integration specific and given to you when you request a testing environment. The refresh_token parameter is the refresh token you got as a response to the authorization code request during initial authentication. The response to the above request contains a new access tokens and looks as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS10ZXN0LnByb2NvdW50b3IuY29tIiwiYXVkIjoiY2xpZW50X2lkIiwic3ViIjoyNjUzNSwiY2lkIjoxNDE1OSwianRpIjoiN2Q0NDQ4NDAtOWRjMC0xMWQxLWIyNDUtNWZmZGNlNzRmYWQyIiwiYXV0aF90aW1lIjoxNjA3OTYyNDc5LCJpYXQiOjE2MDc5NjYwNjYsImV4cCI6MTYwNzk2OTY2Nn0.gxS7K-PT3Gxje6uWwZiWcFC16JkeIeJpUY_KUV8skng",
  "expires_in": 3600
}

A refresh token is valid for six months (15552000 seconds) from the time of issuing. The refresh token is invalidated in any of the following situations:

  • The token runs past its expiration date
  • A connected access token is invalidated using the /logout endpoint
  • User changes their password in Procountor
  • User is removed from the company the refresh token is connected to
  • There are already 100 refresh tokens for the same (API client, company, user) combination and a new refresh token is requested. In this case the oldest refresh token will be invalidated.

When a refresh token is invalidated all access tokens connected to it are invalidated as well.

Two-factor authentication

Some of the API endpoints require using two-factor authentication. This authentication is done by using Finago Key app. This app is available for Android, Apple and Windows devices.

By rule two-factor authentication is required for endpoints which trigger financial transactions. Also some of the endpoints modifying user or company data and settings do require two-factor authentication. The flow for API endpoints requiring two-factor authentication is as follows:

  1. Client application sends request to API to perform an action
  2. API validates the request, and if it's ok, returns 202 Accepted with a transaction ID
  3. Finago Key app prompts the user for a confirmation of the action
  4. User confirms the action in the Finago Key app
  5. The action is completed in Procountor
  6. Client application gets notified of the action in one of the following ways
    1. If the client application has registered a webhook for the matching action type the webhook gets a confirmation of the action
    2. The client application can check the status of action from a confirmation endpoint using the transaction ID from step 2

The confirmation request sent to the user will expire in 5 minutes. If the action is not confirmed by then it will be cancelled. The API confirmation endpoint will provide status of an action for 24 hours from when the action was initiated. See the API reference for full documentation on different HTTP codes and messages returned in different situations.

Two-factor authentication is not enabled in testing environment. The test server will always accept any actions requiring two-factor authentication.

Changing or resetting user passwords

The production server offers possibility to change or reset user's password without needing to log in to the Procountor UI.

On the testing server the user and password management needs to be performed using the Procountor UI.

Changing password

User's password can be changed using the following URL: https://secure.procountor.com/procountor/login?password_change.
The flow to change the password goes as follows:

  1. User navigates to change password page
    • User fill in username, current password and new password (twice). If the new password matches the minimum criteria (at least eight characters, characters from two different groups) the Change password button is enabled.
    • User clicks the Change password button
  2. User receives an SMS containing a verification code. Meanwhile the user is forwarded to a verification page.
    • User enters the verification code and clicks Confirm. If the verification code is correct their password is changed.
  3. User is forwarded to notification page and informed that the password has been successfully changed.

Resetting password

User's password can be reset from the reset link in the API login view. The login page url https://secure.procountor.com/procountor/login must contain the following mandatory query parameters:

  • password_reset
    • Specifies the password reset view. The value should be left empty: password_reset
  • client_id
    • The API client id for your integration. Example: client_id=example_client_id
  • redirect_uri
    • This URI is used to specify where the user is redirected after a succesful password reset and log in. The value is specific to integration and the same than with the normal API login. Example: redirect_uri=https://www.example.com

With all the parameters in place, the the URL will look like the following: https://secure.procountor.com/procountor/login?password_reset&client_id=example_client_id&redirect_uri=https://www.example.com&response_type=code
The flow to reset the password goes as follows:

  1. User navigates to reset password page
    • User enters their username. An email with a reset password link and an SMS with a verification code will be sent to the user. Meanwhile the user is redirected to a notification page.
  2. User clicks the link in the email which opens reset confirmation page
    • User enters the verification code and a new password, and clicks Reset password. If the verification code is correct the user's password is changed.
  3. User is forwarded to notification page and informed that the password has been successfully changed.