FortesMilestones OAuth2 documentation

When FortesMilestones API is used by a client, user account under which the API operations are performed, is identified by an access token instead of a user name and password.
Access token is issued to client aplication when user authorizes use of his account to the client application, in exchange of a one-time authorization code.
As soon as the client application receives an access token, it can perform any API operation under associated account as approved by owner of the account.

There are two API endpoints concerning OAuth2:

The following picture shows overview of typical flow. Although OAuth2 (as per RFC6749) offers other authorization flows as well, FortesMilestones only supports authorization code flow.

Set-up of client ID and client secret is only performed once. Client secret and refresh token should be stored in a secure way by the client application since they represent actual credentials of the user who authorized it.

Step 1: Obtain Client ID and Client Secret

To get a Client ID and Client Secret, you need to create an OAuth application in FortesMilestones. You also must specify a Redirect Uri there. This Uri is used to pass authorization code to the client application. Make sure you configure the Redirect Uri as the endpoint your client application listens on.

Step 2: Set up authorization

When you have a Client ID, Client Secret and Redirect Uri, you can make an authorization request to obtain authorization code.

Example
GET https://qicsmilestones.qics.nl/api/oauth2/oauth2/auth?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>

Note: Redirect Uri configured for the OAuth application in Step 1, must be part of redirect_uri passed in the GET request above. Additional query string parameters are allowed and are preserved in redirect after successful authorization.

Step 3: Get access token

The access token is used to authorize API requests. Authorization code from Step 2 is exchanged for first access token and refresh token.

Example
Request
POST https://qicsmilestones.qics.nl/api/oauth2/oauth2/token
request body: grant_type=authorization_code&code=<code>&client_id=<client_id>&client_secret=<client_secret>&redirect_uri=<redirect_uri>
Response
{
    access_token: "90f4068dfb914dd5aa9d46b1d08b3ef1",
    token_type: "bearer",
    expires_in: 3600,
    refresh_token: "792c136bce02493fa6b28788ae3de7a2"
}

The returned access_token can now be used to access FortesMilestones API for next 3600 seconds. Add authorization header to API requests, such as:

Authorization: Bearer 90f4068dfb914dd5aa9d46b1d08b3ef1

Step 4: Refresh access token

Since access token expires after some time, it must be periodically renewed. This is done by exchanging a refresh_token for new access_token and new refresh_token. The old access_token and refresh_token are invalidated and only new access_token can be used in API. Use the new refresh_token to renew both tokens again.
Request
POST https://qicsmilestones.qics.nl/api/oauth2/oauth2/token
request body: grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>
Response
{
    access_token: "d8a8a3aaf34b4af8b89ddb65000fc4e9",
    token_type: "bearer",
    expires_in: 3600,
    refresh_token: "f9284bc0c8184f91be0769c4cce89b33"
}