Connect using Oauth2

We support 3 grant types. 1. Authorization code (default), 2. Client credentials and 3. Password.
The second grant type is very limited used and is only after collaboration with Profix Support Desk and is ment for applications without an user interface.
Password will only be provided if this is absolutely necessary. A code review can be required. We discourage the use of this type.

A Client ID / Client Secret are only allowed one method, which will be predefined.

 

1. Authorization Code (Default)

In this manual we will explain how to get connected using oauth2

Step 1: Set up authorization requests

  1. When you have your registration containing the Client ID, Client Secret, and Redirect URI, you can make the authorization request.

    2. Example

    GET .../Authorization with the following parameters:

    client_id: b81cc4de-d192-400e-bcb4-09254394c52a
    redirect_uri: https://www.mycompany.com/myapplication

    Actual request:

    GET https://api.profix-it.nl/Authorization?client_id=b81cc4de-d192-400e-bcb4-09254394c52a&redirect_uri=https%3A%2F%2Fwww.mycompany.com%2Fmyapplication

  2. The Profix AGF login screen will be displayed. The user can log in with their Global Profix credentials.
  3. When you have completed this step, a response is sent to the redirect URI with an authorization code.
    • This code is only valid for three minutes.
    • The url of the Redirect URI must be exactly the same as the Redirect URI that you registered in the app registration.

    4. Actual response:
    https://www.mycompany.com/myapplication?code=XTzM!IAAAACbPTzQJXwFhM...

    Error Responses:

    The following authorization errors can occur:

    1. The user is not recognized and has not been authenticated. For example when an incorrect redirect URI is sent in the request, the authorization server will not redirect the resource owner to the redirect URI.
    2. The user authenticated correctly. In the case of an error the following error response is included in the redirect URI:
      • error - displays a predefined error code as show in the OAuth 2.0 Authorization Framework. See OAuth 2.0 Authorization Framework.
      • error_description - displays a human-readable UTF-8 encoded text describing the error.
        This error message is intended for a developer and not an end user.

Step 2. Get and use access tokens

The access token is used to authenticate your API requests.

  1. The authorization code returned in step 1 can be used once to obtain an access token.

    2. Example

    POST ../token with post data:
    (Post data should be x-www-form-urlencoded)

    {
       code: “XTzM!IAAAACbPTzQJXwFhM”,
       grant_type: “authorization_code”,
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”
    }

  2. You receive the following response:

    3. {
       access_token: “AAEAAGxWulSxg7ZT-MPQMWOqQmssMzGa…”,
       token_type: “Bearer”,
       expires_in: 600,
       refresh_token: “Gcp7!IAAAABh4eI8DgkxRyGGyHPLLOz3y9Ss…”
    }

  3. Use the access token in your API requests header.
    4. Your access token expires after 10 minutes. When it has expired you must use the refresh token to request a new access token.

    Add the access token to the authorization header:

    Key: authorization
    Value: Bearer AAEAAGxWulSxg7ZT-MPQMWOqQmssMzGa…

Use refresh tokens efficiently

When your access token expires after 10 minutes, you must use the refresh token to request a new access token. When you request an access token, you can see in the response that the access token is valid for 600 seconds. There are a two things you must note so you can manage these limitations efficiently:

Do not request a new access token too late
Use your refresh token to get a new access token before it expires. If you make an API call with an expired access token, your call will be rejected with response code 401 and reason Authentication Required.

Step 3. Obtain new access tokens

When your access token expires, use the refresh token to obtain a new access token.

  1. POST ../token with post data: (Post data should be x-www-form-urlencoded)

    2. {
       refresh_token: “Gcp7!IAAAABh4eI8DgkxRyGGyHPLLOz3y9Ss …”,
       grant_type: “refresh_token”,
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”,
    }

  2. You receive the following response:

    3. {
       access_token: “AAEAABIKSw2E5nHI8lhwdM4iEV4RPdxLgThZj…”,
       token_type: “Bearer”,
       expires_in: 600
       refresh_token: “__1P!IAAAACpjBagWscm76YIGMY3526T3dIK…”
    }

Result

You now have a new access token that is valid for 10 minutes, and a new refresh token. You can use your new refresh token to receive a new access token. Your old refresh token is no longer valid.

When your access token has expired you have to use the latest refresh token to obtain a new access token.

 

Any accesstoken is valid on all API Url's (so, the tokens can be shared between api.profix-it.nl and api.profix-it.be

 

 

2. Client credentials

Get and use access tokens

The access token is used to authenticate your API requests.

  1. The client credentials can be used once to obtain an access token.

    2. Example

    POST ../token with post data:
    (Post data should be x-www-form-urlencoded)

    {
       grant_type: “client_credentials”,
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”
    }

  2. You receive the following response:

    3. {
       access_token: “AAEAAGxWulSxg7ZT-MPQMWOqQmssMzGa…”,
       token_type: “Bearer”,
       expires_in: 600,
    }

  3. Use the access token in your API requests header.
    4. Your access token expires after 10 minutes. When it has expired you can request a new token.

 

 

3. Password

Get and use access tokens

The access token is used to authenticate your API requests.

  1. The password can be used once to obtain an access token.

    2. Example

    POST ../token with post data:
    (Post data should be x-www-form-urlencoded)

    {
       grant_type: “password”,
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”
       username: “support@profix-it.nl”
       password: “my-password”
    }

  2. When the user can login, You receive the following response:

    3. {
       access_token: “AAEAAGxWulSxg7ZT-MPQMWOqQmssMzGa…”,
       token_type: “Bearer”,
       expires_in: 600,
       refresh_token: “Gcp7!IAAAABh4eI8DgkxRyGGyHPLLOz3y9Ss…”
    }

  3. Use the access token in your API requests header.

Password change

  1. It is possible that the user is required to change password before login is allowed. Then you get the following response

    2. {
       userid: “123”,
       RequireChangePassword: true,
    }

  2. In that case you have to let the user create a new password and you can send the next request

    3. POST ../token/ChangePassword with post data:
    (Post data should be x-www-form-urlencoded)

    {
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”
       userid: “123”
       password: “old-password”
       newpassword: “new-password”
    }

  3. You get a response like this:

    4. {
       success: true,
       message: “You can now login”
    }

  4. or

    5. {
       success: false,
       message: “User friendly notification what went wrong”
    }

  5. When success = true, you can request a token again with the new password.

When your access token expires, use the refresh token to obtain a new access token.

  1. POST ../token with post data: (Post data should be x-www-form-urlencoded)

    2. {
       refresh_token: “Gcp7!IAAAABh4eI8DgkxRyGGyHPLLOz3y9Ss …”,
       grant_type: “refresh_token”,
       client_id: “b81cc4de-d192-400e-bcb4-09254394c52a”,
       client_secret: “n3G7KAhcv8OH”,
    }

  2. You receive the following response:

    3. {
       access_token: “AAEAABIKSw2E5nHI8lhwdM4iEV4RPdxLgThZj…”,
       token_type: “Bearer”,
       expires_in: 600
       refresh_token: “__1P!IAAAACpjBagWscm76YIGMY3526T3dIK…”
    }

    You now have a new access token that is valid for 10 minutes, and a new refresh token. You can use your new refresh token to receive a new access token. Your old refresh token is no longer valid.

    When your access token has expired you have to use the latest refresh token to obtain a new access token.

Use refresh tokens efficiently

When your access token expires after 10 minutes, you must use the refresh token to request a new access token. When you request an access token, you can see in the response that the access token is valid for 600 seconds. There are a two things you must note so you can manage these limitations efficiently:

Do not request a new access token too late
Use your refresh token to get a new access token before it expires. If you make an API call with an expired access token, your call will be rejected with response code 401 and reason Authentication Required.