Implementing authorization

API login page and different use cases

Home  ⫽ General information  ⫽ Implementing authorization

Implementing authorization

The authorization process for testing purposes requires the user's username, password and company ID to be known. Consequently, is not suitable for all situations.

In integrations to be used by one end-user company only, each of the credentials can be determined in advance and saved in the application using the API. In integrations with software to be used by several end-user companies, the credentials cannot be saved in the external application.

As a solution, there is a possibility to implement support for Procountor API login page as explained below. The examples following it present solutions for three types of different integration cases.

Procountor API login page

Procountor API login page is a webpage for authenticating users on Procountor's server. It requires logging in with Procountor username and password and returns an authorization code to the external application.

On the login page, users choose a Procountor environment they would like to grant the external application access to. As a result, the authorization code the external application receives is linked to a particular user in a particular environment.

By using Procountor API login page, the external application does not need to handle Procountor usernames, passwords or company IDs. It can exchange the authorization token for an access token by making a request to the access token endpoint.

Note: Do not consider bypassing the API login page and asking users to type and store their Procountor passwords in your application.

Accessing the page

The API login page is located in the following path:

/login?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<state>

Example: On the api-test server, the location is:
https://api-test.procountor.com/login?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<state>.

The external application should redirect the user's browser to this URL. For instance, the UI of the external application might have a button triggering this action, with text "Grant access to Procountor" or similar.

Returning from the page

Once the user has authenticated and selected an Procountor environment on the login page, the user's browser will be redirected to the location indicated by redirect URI. The location will have two URL parameters: code and state. The code parameter contains an authorization code for the user. The state parameter holds the value set by the external application when the user was redirected to the login page.

To conclude, the user's browser will be redirected to the following location in the external application:

<redirect_uri>?code=<authorization code>&state=<state>

Example: If your domain is example.com, the location could be https://example.com/auth/procountor/?code=af6b4e...&state=1234567890.

Information: You can define the redirect URI for your application by contacting us. Mention your client ID and the new redirect URI.

After receiving it, the external application should exchange the authorization code for an access token. This can be achieved by utilising the process also used for obtaining access tokens for testing purposes. With the authorization code, continue the process from step 2.

Note that the process for obtaining an access token must be performed on the server side. From the user's perspective, the page at redirect URI should provide a possibility to move forward in the external application once the access token has been acquired.

Conclusion

As a conclusion, below is a possible flow for a fully implemented authorization process:

  1. The user clicks a button "Grant access to Procountor" in an external application.
  2. The user's browser is redirected to Procountor API login page.
  3. The user logs in with Procountor username and password.
  4. The user chooses a Procountor environment the access is granted to.
  5. The user's browser is redirected back to the external application to the location indicated by redirect URI.
  6. The external application reads the authorization code.
  7. The external application makes a server-side request to the access token endpoint and receives an access token for the user.
  8. The external application starts using Procountor API with the acess token.

The first image below depicts the two steps on the API login page. The second, in turn, illustrates a possible implementation of API login page support.

API login page OAuth implementation example

Case 1: Several end-user companies

Utilise this approach if the integration will be used by several end-user companies. This is the case when building an integration with publicly available software, and it is not known which end-users will take the integration into use in the future.

Solution

As the Procountor user accounts and environments used are not fixed, the required values for username, password and company ID cannot be determined in advance. Consequently, there is a need to acquire an authorization code for each user without knowing those credentials. Once acquired, the authorization code can be exchanged for an access token.

For acquiring the authorization code, use Procountor API login page as described earlier on this page. To setup the integration, the end user has to create a new user account in their Procountor environment and use it on the API login page.

Taking the integration into use

This is an example of the flow of setting up the integration for a particular end user:

  1. An user creates a new user account with necessary user rights in their Procountor environment.
  2. The user clicks a button (like Grant access to Procountor) in the external application and is forwarded to Procountor API login page.
  3. The user logs in with the new user account on the API login page and selects the target Procountor environment.
  4. The user's browser is redirected to redirect URI, and the external application receives an authorization code.
  5. The external application exchanges the authorization code for an access token.
  6. The external application stores the access token and uses it for API requests.

Question: Why is the customer required to create a new user account for API access?

Answer: External applications using the API should only have access to the necessary parts of customer environments. For instance, if using a main user account with the integration, the external application probably receives too extensive rights to the environment. Additionally, all interactions made through the API appear to be made by the particular user account.

By using a dedicated account for integrated software, the external application maximises the probability of keeping the access token valid. Finally, using a dedicated account allows the user to easily revoke access from external applications if needed.

Case 2: One end-user company

These instructions apply if the integration will be used by one end-user company only. This might be the case when building an integration with internal software of a company. Notice that the approach of case 1 can be used in this situation as well.

Solution

As the Procountor user account and environment involved are fixed, the required values for username, password and company ID can be determined in advance and saved in the external application. The application can obtain an access token by first acquiring an authorization token grant like in the authorization process for testing purposes.

When moving the integration into production, mention the Business ID of the Procountor environment you would like to access. We will provide you with the corresponding company ID.

Note: This approach is not suitable for integrations with publicly available software. Procountor will not provide company IDs for Procountor environments once the integration has been started in production.

Taking the integration into use

This is an example of the flow of setting up the integration:

  1. Create a new user account with necessary user rights in the target Procountor environment.
  2. Store the username, password and company ID in the external application.
  3. The external application should now obtain access token and store it for using with API requests.

Case 3: End-user companies with several users

Use this approach if you wish to use Procountor API so that all actions made by different persons appear to be made with respective user accounts. This is often the case when some irregular actions on the UI of the external application trigger usage of Procountor API.

Solution

Implement support for Procountor API login page. In this case, users can log in with their personal Procountor credentials on the API login page. You can choose to store the access tokens received in the external application or, if API usage takes place rarely enough, require users to authenticate every time.

Using the integration

This is an example of the flow of using the integration:

  1. A user clicks a button (like Transfer this data to Procountor) in the external application and is forwarded to Procountor API login page.
  2. The user logs in with personal Procountor credentials.
  3. The user's browser is redirected to redirect URI, and the external application receives an authorization code.
  4. The external application exchanges the authorization code for an access token.
  5. The external application may store the access token and use it for API requests.