---
title: "REST - ExtAuth"
canonical: "https://help.agiloft.com/space/HELP/703889445/REST+-+ExtAuth"
format: markdown
---
Agiloft supports bearer token authorization for REST API access. Access tokens allow client applications to make REST API calls on behalf of an authorized user. The authorization process can also return a refresh token, which is used to obtain a new access token after the original token expires.

Agiloft provides two authorization mechanisms for REST API access:

- **[OAuth 2.0](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43716464)**: Recommended for new integrations and third-party applications.
- **ExtAuth**: A legacy authorization mechanism that remains available for backward compatibility with existing integrations and some internal use cases.

Both mechanisms issue bearer access tokens, but they use different endpoints, configuration options, and authorization models.

## Create API Settings

To configure access token authorization, go to **Setup > Integration > Access Token API Setup** and create a new API Settings entry.

When you create API Settings, configure the following fields:

| Field | Description |
| --- | --- |
| **Client ID** | Identifies the API Settings entry during authorization and token requests. |
| **Client Secret** | Used to authenticate the settings entry during token refresh. |
| **Settings Name** | Internal name for identifying the settings entry. |
| **Display Name** | User-facing name shown during authorization. |
| **Assigned Group** | Defines which users are allowed to receive an access token. REST API requests are made on behalf of the user who receives the token. |
| **Redirect URI** | The client application URL where users are redirected after authorization. |
| **Scope** | Optional list of REST API operations allowed for users who authorize through this settings entry. |

After entering the required information, click **Save** or **Apply**.

If the **Client ID** and **Client Secret** fields are empty, click **Enable** to activate the settings entry. To block the settings entry later, click **Disable**.

## Configure Scope Permissions

The optional **Scope** field limits which REST API operations are available to users who receive an access token.

Use the following format to define user-specific permissions:

```
username1:[operation1, operation2, ...]; username2:[operation1, operation2, ...]; [defaultOperation1, defaultOperation2, ...]

```

Where:

- `username1`, `username2` are existing Agiloft users.
- `operation1`, `operation2` are REST API operation names.
- The final bracketed list without a username defines the default operations for users not explicitly listed.

If no default operation list is included, users who are not listed in the Scope field can access all REST operations. If the Scope field is blank, all users who authorize through the settings entry can access all REST operations without limitation.

Supported REST operations include:

```
EWCreate
EWRead
EWUpdate
EWDelete
REST
EWBroadcast
EWSelect
EWSearch
EWGetChoiceLineId
EWHotlinks
EWAttach
EWRetrieve
EWRemoveAttachment
EWOData
EWTable
EWSavedSearch
EWAttachInfo
webhooks
EWActionButton
EWAsyncStatus

```

## Change API Settings

If you change API Settings after authentication is complete or after an access token has been issued, users should re-authenticate before continuing to use the integration.

Recommended process:

1. Revoke the existing access token.
2. Make the required changes in API Settings.
3. Obtain a new access token.

Changing **Token Expiry in Seconds** does not require re-authentication. The new value takes effect the next time an access token is requested.

## ExtAuth Authorization Flow

The ExtAuth authorization flow uses browser-based user authorization and a token exchange process.

The standard flow includes the following steps:

1. The client redirects the user to the authorization endpoint.
2. The user signs in and approves access.
3. Agiloft redirects the user back to the client application with an authorization code.
4. The client exchanges the authorization code for an access token and refresh token.
5. The client uses the access token in REST API requests.
6. The client uses the refresh token to request new access tokens when needed.

## Authorization Request

Direct the user’s browser to the following endpoint:

```
GET /ewws/extauth

```

By default, the request content type is:

```
application/x-www-form-urlencoded

```

Use the following query parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `response_type` | Yes | Must be `code`. |
| `client_id` | Yes | Client ID from the API Settings entry. |
| `redirect_uri` | Yes | Redirect URI registered in the API Settings entry. |
| `scope` | Conditional | Defines the REST API operations requested for the access token. |
| `state` | Recommended | Returned to the client after authorization. Recommended for CSRF protection. |
| `async_status` | No | Set to `Yes` to enable authorization status tracking. |
| `type` | No | Set to `extended` to bypass the default content type requirement. |

Example request:

```
GET /ewws/extauth?response_type=code&redirect_uri=https%3A%2F%2Ftest.com%2Freceiver&client_id=Bvn7k4fIdMEZQrJJ7ZCIQgErlTDbX9L73LThA5YA4W0%3D&scope=%5BEWRead%2C%20EWCreate%5D&state=LQKFNL023478_3259423

```

If authorization succeeds, Agiloft redirects the user to the configured `redirect_uri` with the following parameters:

| Parameter | Description |
| --- | --- |
| `state` | The original state value, if provided. |
| `code` | Authorization code used in the access token request. The code is valid for 5 minutes. |
| `api_access_point` | Base URI to use for REST API calls with the access token. If empty, use the base URI of the KB server. |
| `client` | System information. |

Example success redirect:

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

```

If authorization fails, Agiloft redirects the user to the `redirect_uri` with the following parameters:

| Parameter | Description |
| --- | --- |
| `error` | Error code. |
| `error_description` | Details about why the request failed. |

Possible error codes include:

| Error code | Description |
| --- | --- |
| `invalid_request` | The request is missing a required parameter, includes an invalid value, includes a parameter more than once, or is otherwise malformed. |
| `unauthorized_client` | The client is not authorized to request an authorization code using this method. |
| `access_denied` | The resource owner or authorization server denied the request. |
| `unsupported_response_type` | The authorization server does not support obtaining an authorization code using this method. |
| `invalid_scope` | The requested scope is invalid, unknown, or malformed. |
| `server_error` | The authorization server encountered an unexpected condition. |

## Access Token Request

After receiving an authorization code, send a POST request to the token endpoint:

```
POST /ewws/exttoken

```

Use the `api_access_point` value returned in the authorization response, if provided.

Request parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `grant_type` | Yes | Must be `authorization_code`. |
| `code` | Yes | Authorization code from the previous step. |
| `client_id` | Yes | Client ID from the API Settings entry. |
| `redirect_uri` | Yes | Must match the redirect URI used in the authorization request. |

Example request:

```
POST /ewws/exttoken HTTP/1.1
Host: yourdomain.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

```

Example response:

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

```

Response fields:

| Field | Description |
| --- | --- |
| `access_token` | Bearer token used in REST API requests. |
| `refresh_token` | Token used to request a new access token. |
| `token_type` | Always `Bearer`. |
| `expires_in` | Access token expiration time, in seconds. |

## Refresh an Access Token

Use the refresh token to request a new access token.

Send a POST request to:

```
POST /ewws/exttoken

```

Request parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `grant_type` | Yes | Must be `refresh_token`. |
| `md5_secret` | Yes | First 20 characters of the Client Secret from the API Settings entry. |
| `refresh_token` | Yes | Refresh token issued during the access token request. |

Example request:

```
POST /ewws/exttoken HTTP/1.1
Host: yourdomain.com
Content-Type: application/x-www-form-urlencoded

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

```

Example response:

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

```

Refresh tokens expire after 28 days of inactivity. Refresh tokens can also be revoked by the authorizing user, so client applications must handle revoked access gracefully.

## Revoke Tokens

Access tokens and refresh tokens can be 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 access tokens issued from that refresh token are revoked.

To revoke a token, send a POST request to:

```
POST /ewws/extrevoke

```

Request parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `revoke_for` | Yes | Refresh token or Client Secret from the API Settings entry. |

Example request:

```
POST /ewws/extrevoke HTTP/1.1
Host: yourdomain.com
Content-Type: application/x-www-form-urlencoded

revoke_for=LKHEFOP932875KJGKJG32423542LHLKHFD_FDKLJ.OJ%3D%3D

```

If the request succeeds, Agiloft returns HTTP 200 with an empty body.

If the request fails, Agiloft returns HTTP 400 with an error response:

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

```

## Track Authorization Status

To track the latest status of an authorization procedure, include the following parameter in the original authorization request:

```
async_status=Yes

```

Status updates are available for up to 7 minutes.

To retrieve the latest status, send a POST request to:

```
POST /ewws/extauth

```

Request parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `type` | Yes | Must be `authstate`. |
| `client_id` | Yes | Client ID from the API Settings entry. |

Example request:

```
POST /ewws/extauth HTTP/1.1
Host: yourdomain.com

type=authstate&client_id=KDVViuP84plGx01pHAp63ipZ38HlVIthkDqi68sA8%2BHfKbhfUCgVdjxyZB1o%2FMdc

```

Example response:

```
{
  "auth_phase": "GetAccessToken",
  "status": "Error",
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is expired or revoked."
}

```

Response fields:

| Field | Description |
| --- | --- |
| `auth_phase` | Current phase of the authorization procedure. |
| `status` | Latest status for the current phase. |
| `error` | Optional error code. |
| `error_description` | Optional error description. |

Possible authorization phases:

| Phase | Description |
| --- | --- |
| `Authorization` | Authorization procedure was requested. |
| `UserCredentials` | User must confirm credentials on the login page. |
| `AccessConfirmation` | User must confirm access on the authorization page. |
| `GetAccessToken` | Access token was requested. |

## Simple Authorization

Simple authorization combines authorization and token issuance into a single request. This method is not recommended because it does not provide the same level of protection as the standard authorization flow.

By default, Simple authorization is disabled.

To enable Simple authorization:

1. Go to **Setup > System > Manage Global Variables**.
2. Add a global variable named `enable_simple_otoken`.
3. Set the variable type to **Yes/No choice list** or **Short Text Constant**.
4. Set the value to **Yes**.

To request tokens using Simple authorization, send a POST request to:

```
POST /ewws/extauth

```

Request parameters:

| Parameter | Required | Description |
| --- | --- | --- |
| `type` | Yes | Must be `simple`. |
| `kb_name` | Yes | KB name. |
| `login` | Yes | User login. |
| `password` | Yes | User password. |

Example request:

```
POST /ewws/extauth HTTP/1.1
Host: yourdomain.com
Content-Type: application/x-www-form-urlencoded

type=simple&
kb_name=Demo&
login=user_login&
password=user_passwd

```

Example response:

```
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyXflefjkln",
  "refresh_token": "h3drI0VkT1FQug7P63rX0GJQWIbnrGljQC4VjmnDD5o=",
  "token_type": "Bearer",
  "expires_in": 15
}

```

In Simple authorization, `expires_in` is returned in minutes. The default value is 12 or 15 minutes.

For Simple authorization refresh requests, the `md5_secret` parameter can contain any value.