Legacy authentication method
The legacy authentication method offers a way to authenticate against the API without the need to pass through the API login UI. This method requires passing user credentials through the API and thus is not recommended to be used. We are offering this method for those integrations which are, for a reason or another, not able to direct the user to our API login UI.
This authentication method is considered deprecated and will be removed in April 2021 version.
We are currently working towards providing an authentication method following the OAuth 2.0 Client Credentials flow to replace the legacy authentication method described on this page.
Authentication flow
This method works much like the current recommended authentication flow except that the authorization code is received by calling the API /oauth/authz endpoint instead of going through the API login UI. The first step is to POST the user credentials to the aforementioned endpoint.
POST /api/oauth/authz?response_type=code&client_id=<client_id>&state=<state> HTTP/1.1
Content-Type: application/x-www-form-urlencoded
response_type=code&
username=<username>&
password=<password>&
company=<company>&
redirect_uri=<redirect_uri>
The client_id and redirect_uri parameters are integration specific and given to you when you request a testing environment. The username and password parameters are user specific authentication credentials and should be handled with care. The company is the ID for the company the user wishes to log in to as used by Procountor. This ID is not available from Procountor UI but can be received by performing a regular API login using the API login UI and checking the contents of the access token or by calling the /sessioninfo endpoint. The state parameter is optional, implementation specific, and will be returned with the authorization code.
Succesful call to /oauth/authz endpoints redirects the caller to the redirect URI with authorization code and state.
HTTP/1.1 302 Found
Location: <redirect_uri>?code=<authorization_code>&state=<state>
From here on out the authentication flow matches what's described on the API authentication page. The authorization code is traded for an access and a refresh token using the /oauth/token endpoint.
POST /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 from the API authentication page.