Accessing the API

Authorization and authentication with Procountor API

Home  ⫽ General information  ⫽ Accessing the API

Accessing Procountor API

Accessing Procountor API requires authorization and authenticating: users need to prove with an access token they have a grant to use the API. As the method for authorization, the API utilises an adapted OAuth2 process.

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

Information: OAuth 2.0 is a framework where users of a service can allow a third-party application to access their data hosted in the service, without revealing their credentials (username and password) to the application.

First, this page presents the process for obtaining an access token for an individual user for testing purposes. Second, the instructions show how to use the access token with API requests. Ultimately, the page lists solutions for the most common problems with authorization.

Prerequisites for testing access

The following credentials are required for obtaining a grant to use the API for testing purposes. They can be acquired by submitting a request for a testing environment.

  • Username
  • Password
  • Company ID
  • Client ID
  • Client secret
  • Redirect URI

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 redirect URI in your testing environment request, it defaults to 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 has to be saved in API client details by Procountor before using it. To define or change the redirect URI after receiving your testing environment, drop us a line and state your client ID and the new redirect URI.

Obtaining a grant for testing

Before making actual requests to Procountor API endpoints, there are two steps of going through an OAuth2 authorization process. First, you need an authorization code. After that, you may obtain an access token by using the authorization code. Notice that this process may differ in the complete integration, depending on your use case.

Important note

The process described below allows to obtain access to the API for testing purposes. It is not suitable for integrations to be used by more than one end-user companies. More information on implementing authorization is presented later on this page.

Step 1: Authorization code grant

The authorization code is a grant for a user of your application and can be later exchanged for an access token. Obtain the authorization code by posting a request to our API (testing) server as the example below shows. Replace all values in angle brackets, including the brackets, with the corresponding values. Supply all values as URL encoded.

Information: More information about URL encoding, also known as Percent-encoding, can be found on Wikipedia. For correctly implementing the encoding, refer to the documentation of your programming language or framework.

Request schema

POST https://api-test.procountor.com/api/oauth/authz

URL parameters:
response_type=code
client_id=<client_id>
state=<state>

POST parameters:
response_type=code
username=<username>
password=<password>
company=<company>
redirect_uri=<redirect_uri>

Headers:
Content-Type: application/x-www-form-urlencoded

Example: If your password is abc?d, the string password=<password> should be password=abc%3Fd in the request.

Value of the state parameter may be chosen arbitrarily or omitted. It can be utilised to pass data from your application through the authorization process. Possible uses include e.g. preventing CSRF vulnerabilities in cases where support for Procountor API login page is implemented.

cURL example

curl -X POST "https://api-test.procountor.com/api/oauth/authz?response_type=code&client_id=<client_id>&state=<state>" \
-d "response_type=code" \
-d "company=<company>" \
--data-urlencode "username=<username>" \
--data-urlencode "password=<password>" \
--data-urlencode "redirect_uri=<redirect_uri>" \
-H "Content-Type:application/x-www-form-urlencoded" \
-v

Response

A successful response is returned with HTTP status code 302. It contains a Location header with your authorization code as the value of URL parameter code. The value is a long hexadecimal string. As the example below shows, the state parameter is also present here.

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

Please note that some REST tools such as Postman may try to automatically redirect to the URI indicated by the Location header without displaying the actual response from the server. If you are encountering errors when testing the authorization process with such tools, this might be the reason. Also notice that the authorization code will expire after expires_in seconds (starting from v5).

Step 2: Access token

Now that you have obtained an authorization code, you may proceed with exchanging it for an access token. Pass the authorization code and required URL query parameters in a POST request:

Request schema

POST https://api-test.procountor.com/api/oauth/token

POST parameters:
grant_type=authorization_code
redirect_uri=<redirect_uri>
code=<code>
client_id=<client_id>
client_secret=<client_secret>

Headers:
Content-Type: application/x-www-form-urlencoded

cURL example

curl -X POST "https://api-test.procountor.com/api/oauth/token" 
-d "client_id=<client_id>"  
-d "client_secret=<client_secret>" 
-d "grant_type=authorization_code" 
-d "redirect_uri=<redirect_uri>" 
-d "code=<code>" 
-H "Content-Type:application/x-www-form-urlencoded" 
-v

Response

A successful request will produce a response with HTTP status 200. The response body contains your access token which is a long hexadecimal string. The access token represents a particular user in a particular environment, using a particular API client.

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

Body:
{
    "access_token" : "b4a24f...",
    "refresh_token" : "c2b6ca...",
    "expires_in" : 3600
}

Starting from v5, the refresh_token field contains a token that can be used to obtain a new access token before or after the current token has expired. The expiration time is indicated in seconds by the expires_in field.

Implementing authorization

The process for authorization described earlier is not suitable for integrations to be used by several end-user companies. Read more about implementing authorization for different types of integrations on a separate page:

Read how to implement authorization

Note: Do not consider asking users to type and store their Procountor passwords in your application.

Operating with access tokens

Providing a token

An access token must be supplied with every request to the API unless otherwise stated. Include the following header information in your requests:

Authorization: Bearer <access token>

Example: If your access token is b4a24f..., supply a header Authorization: Bearer b4a24f....

Refreshing a token

Starting from v5, access tokens expire in a certain period of time as described earlier. A new access token can be obtained by using a refresh token. This can be done before or after the old access token has expired. To obtain a new access token, make the following request:

Request schema

POST https://api-test.procountor.com/api/oauth/token

POST parameters:
grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<client_id>
client_secret=<client_secret>

Headers:
Content-Type:application/x-www-form-urlencoded

cURL example

curl -X POST -G "https://api-test.procountor.com/api/oauth/token" \
-d "grant_type=refresh_token"
-d "refresh_token=<refresh_token>" \
-d "client_id=<client_id>" \
-d "client_secret=<client_secret>" \
-H "Content-Type:application/x-www-form-urlencoded" \
-v

Response

The response is similar to the one received for the initial access token. It contains a new access token and its expiration time, but no new refresh token as the existing refresh token will not expire.

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

Body:
{
    "access_token" : "d2b24a...",
    "expires_in" : 3600
}

Invalidating a token

To invalidate an access token, make a POST request to /logout endpoint in server root path. Include the usual Authorization header in the request to indicate the access token to be invalidated. Example:

POST https://api-test.procountor.com/logout

Headers:
Authorization: Bearer <access token>

This removes the given access token and the refresh token related to it and also any other access tokens that were created from that refresh token.

Validity of access tokens

Starting from v5, an access token is valid until one of the following events takes place:

  • The access token expires
  • The access token is invalidated using the /logout endpoint
  • The user's password is changed in Procountor
  • The user is removed from the Procountor environment

Troubleshooting

Below are described some of the most common problems and their solutions regarding authorization with Procountor API.

Error messages in authorization

Should you encounter an error message in the authorization process, first check the following points:

  • All required parameters and their values are present in both URL query and body parts of the request.
  • All parameter values including other than alphanumeric characters are URL encoded.

Redirect uri mismatch

The redirect URI must match the one saved for your API client in Procountor database. It cannot be omitted or changed without notifying us. See the section above.

Invalid authorization code

An authorization code can be used only once.

Invalid username or password

The user account must be a member of the target Procountor environment. Procountor user accounts on the production server cannot be used on the testing server, and vice versa.

Client authentication failed

Check that the username, password, client secret and redirect URI are sent as URL encoded.