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. A redirect URI must be a clean URL which does not contain a query string.

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. Client credentials flow is recommended for backend integrations and is also required for any user with "API login only" user right limitation.

Machine to machine authentication

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.

Avoid sending sensitive information (password, API client secret, API key, refresh token, authorization code) in the request URL [OWASP guidelines].

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. The login flow must be completed within a 5 minute period. The login page functionality requires enabling cookies and JavaScript.

API login dialog API company dialog API login session expired

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.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. An access token is not bound to specific API version but can authorize calls to any API version or endpoint. 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

  • Following API endpoints require two-factor authentication:
    • PUT /users
    • DELETE /invoices/{invoiceId}/paymentevents/{paymentEventId}
    • POST /payments/directsalarypayments
    • PUT /payments/directsalarypayments/{paymentlistId}/cancel
    • POST /payments
    • DELETE /payments/{paymentId}
    • POST /payments/directbanktransfers
    • PUT /payments/{paymentId}/cancel

Two-factor authentication is done by using Procountor Key app (available for Android and Apple devices).

Taking Procountor Key into use

To take Procountor Key into use follow these steps:

  1. Go to login page and choose 'Manage Procountor Key devices'.
  2. You will be redirected and asked to provide your username and login.
  3. After successful login you will be asked to confirm your identity:
    1. Using Procountor Key, if you have already paired device
    2. One time password sent via SMS, if no other method accessible
  4. Choose 'Add new device' and confirm your identity
  5. Download Procountor Key application from store
  6. Pair device using one of the possible options:
    1. Pair with a link via SMS - registration link will be sent to you via SMS, link will open application and start pairing process
    2. Pair manually instead - pair using QR code that should be scanned inside Procountor Key application

API login manage devices API device manager

Two-factor endpoints flow

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 and confirmation application code
  3. Procountor Key app prompts the user for a confirmation of the action
  4. User confirms the action in the Procountor 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 your password

The production server offers possibility to change 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.

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.

Problems logging in

In case of logging in problems we are providing 3 options for handling such situations. All are accessible using link 'Problems logging in?' in login page.

I forgot my password (resetting password)

  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.

I forgot my username

  1. User navigates to forgot username page
  2. User enters first name, last name and email address
  3. User click 'Send' button
  4. Email with account details will be sent to email address connected with found account

I lost my device

This option is useful for Procountor Key users only.

  1. User navigates to lost device page
  2. User provides username and password to which lost device was connected
  3. After pressing 'Disconnect' button all devices are disconnected from given account