supports the OAuth Authorization Code Flow to obtain access tokens from our authorization server. It is a secure and flexible flow that can be used by both confidential and public clients. This requires you to configure an OAuth2 client in your knowledgebase (KB) by creating an API application, which requests permission and authentication from the user before performing any API requests on their behalf. When an API request is made, the user is redirected to the API application, asked to authenticate themselves and grant the requested permissions, and then redirected to the web application.

The Authorization Code Flow is considered to be the most secure OAuth flow because it does not expose the access token to the user. It is recommended for use by all clients, but it is especially important for confidential clients that need to store access tokens securely.

Here are some examples of who should use the OAuth Authorization Code Flow:

• Web applications that need to access protected resources on behalf of users.
• Mobile applications that need to access protected resources on behalf of users.
• APIs that need to be accessed by other applications.

's implementation of OAuth2 complies with the OAuth 2.0 specification and provides a variety of security benefits, as described in RFC 6749.

Creating an API Application

The OAuth2 client setup begins with creating and configuring a new API application. When you create the application, you associate it with a specific user in the KB to determine which permissions are used when the server handles a REST API call. All REST API requests will be executed on behalf of this user.

To create an API application:

1. Click the Setup gear in the top-right corner and go to Integration > OAuth2 Client Setup.
2. Click Deploy or Configure:
   • Deploy: The OAuth2 client hasn't been deployed yet. Clicking Deploy configures the OAuth2 client for use in your KB, which can take a few minutes to complete.
   • Configure: The OAuth2 client has already been deployed. Clicking Configure takes you to the API Application screen.
     
3. On the API Application screen, click New to open the API Application Settings wizard.
4. Complete the required fields:
   1. Name: The name that the application uses with's REST API.
   2. Display Name: The name of the application that appears in the KB.
   3. Associate this Application with Contact ID: The ID of the user associated with the application. All permissions for this user are used when the REST API is called. This field is automatically populated when you select a user in the Full Name field.
   4. Full Name: The name of the user associated with the application.
   5. Redirect URI: The webpage where you want to redirect users at the end of the authorization process. The redirect URI specified in your OAuth request must belong to this URI.
   6. Token Expiry in Minutes: The amount of time in minutes before the access token expires. The default value is 15, and the acceptable range is from 1 to 60.
5. Click Apply Changes.

6. Click Enable. This activates the application and generates the Client ID and Client Secret, which are used during the token exchange.
   

   If you need to block your application for any reason, click Disable, which replaces Enable after it's been clicked.

Changing Application Settings

Verify that your application settings are correct so that you don't need to change them later. If you need to change your application's settings but have already completed the authentication procedure described below, you need to re-authenticate for your changes to take effect. If you need to make changes but have already received an access token, you need to revoke the access token, make the changes, and then obtain a new access token for your changes to take effect. See Revoking Tokens for more information.

Changes to the values in the Associate this Application with Contact ID field or the Redirect URI field can sometimes block your application. If this happens, recreate the application with the correct settings.

OAuth Token Exchange

After the API application is created, the OAuth authorization process occurs through a series of HTTP calls made to various endpoints on the KB server. The following section describes the process and serves as a reference for the parameters in each client request and server response.

Authorization Request

The OAuth process starts with the client directing the user's browser to make a request to the /ewws/oauth endpoint, where the Content-Type must be in the form application/x-www-form-urlencoded. The request includes the following query string parameters:

https://example.agiloft.com/ewws/oauth?response_type=code&redirect_uri=https%3A%2F%2Ftest.com%2Freceiver&
    client_id=Bvn7k4fIdMEZQrJJ7ZCIQgErlTDbX9L73LThA5YA4W0%3D&scope=permissions_for%3A213&
    state=LQKFNL023478_3259423

The authorization request asks the user to authenticate themselves and then authorize the request, which redirects the user to the URI value defined for the redirect_uri parameter.

Successful Authorization Request

If the request succeeds, the following query string parameters are sent to the client in response:

HTTP/1.1 302 Found
Location: https://example.agiloft.com/receiver?client=&state=LQKFNL023478_3259423&
    code=EFLJHELFH23487402387LKFEHJFEHF=

Failed Request

If the request fails, the following query string parameters are sent to the client in response:

The following error codes are possible:

Access Token Request

If the authorization request is successful, the client makes an HTTP POST to the /ewws/otoken endpoint by using the api_access_point value retrieved in the previous step. The following parameters are used:

POST /ewws/otoken HTTP/1.1
Host: example.agiloft.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=EFLJHELFH23487402387LKFEHJFEHF&
client_id=Bvn7k4fIdMEZQrJJ7ZCIQgErlTDbX9L73LThA5YA4W0%3D&
redirect_uri=https%3A%2F%2Ftest.com%2Freceiver

Successful Access Token Response

The authorization code from the request is exchanged for OAuth2 tokens, and the server returns a JSON array with the following keys:

{
  "access_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyX2FkbWluI",
  "refresh_token":"LKHEFOP932875KJGKJG32423542LHLKHFD_FDKLJ.OJ==",
  "token_type":"Bearer",
  "expires_in":15
}

Refresh Request

At any time the client can use the refresh token to receive a new access token. To start a request, the client makes an HTTP POST to the /ewws/otoken endpoint by using the api_access_point value retrieved during the authorization request. The following parameters are used:

POST /ewws/otoken HTTP/1.1
Host: example.agiloft.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
md5_secret=F64EC9CE9852EE154696&
refresh_token=LKHEFOP932875KJGKJG32423542LHLKHFD_FDKLJ.OJ%3D%3D

The refresh token can then be used to generate a new access token. The server returns a JSON array with the following keys:

{
  "access_token":"wehRT74iOiJIUzI1NiJ0.weJzdWIiOiIyX2FkbWluI",
  "token_type":"Bearer",
  "expires_in":15
}

Revoking Tokens

Access tokens and refresh tokens can be revoked at any time by the authorizing user. REST operations cannot be performed with a token that has been revoked. If an access token is revoked and it has a corresponding refresh token, the refresh token is also revoked. If a refresh token is revoked, all the access tokens issued from that refresh token are also revoked. 

Refresh tokens can be revoked by making a POST call to the /ewws/orevoke endpoint by using the api_access_point value retrieved during the authorization request. The following parameters are used:

POST /ewws/orevoke HTTP/1.1
Host: example.agiloft.com
Content-Type: application/x-www-form-urlencoded

revoke_for=LKHEFOP932875KJGKJG32423542LHLKHFD_FDKLJ.OJ%3D%3D

Response to Revoking a Token

If the request to revoke the token succeeds, an HTTP success code 200 is returned with an empty body or without any body at all. If the request fails, an HTTP code 400 is returned with the error code INVALID_REQUEST.

{
  "error" : "INVALID_REQUEST",
  "error_description" : "Invalid token."
}