# Configuring the authentication

> One of the big pillars for creating a connector is identifying and correctly integrating its authentication setup. If done
correctly, once the connector is published to the Integration Service catalog, users can create connections to it just like
with any other connector within the catalog.

One of the big pillars for creating a connector is identifying and correctly integrating its authentication setup. If done
correctly, once the connector is published to the Integration Service catalog, users can create connections to it just like
with any other connector within the catalog.

All connectors reuse the authentication framework so that the full authentication flow and connection management can be handled
in a unified approach.

The end-result of authentication is that any subsequent request within this connector uses the result of the authentication
process for every API call. For example, a Bearer token is sent in the headers on every API call:

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-337321-cac957ac.webp)

Connector Builder supports the following industry standards through simple configuration rather than extensive coding:

* OAuth 2.0 Authorization code
* OAuth 2.0 Authorization code with PKCE
* OAuth 2.0 Client credentials
* Basic
* API key
* Personal Access Token (PAT)
* Custom
* No authentication

Since Connector Builder ties into the Integration Service framework, defining your authentication setup is now a matter of
configuration rather than a complex process. This means that the framework deals with token exchanges, refreshes, and any
other such tasks. Connector Builder defaults to OAuth 2.0 Authorization code, since this is the most common vendor approach
to handle authentication.

The authentication page is made out of three components:

1. The **Authentication type**, which drives how the authentication framework reflects with additional validation for PKCE, full token exchange (for OAuth),
   etc. In addition, it also reconfigures the table with properties underneath so that the required properties are outlined.  

   ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-337335-f3f31d9f.webp)
2. The properties table can be modified with custom parameters and/or editing existing ones. Depending on the **Authentication type** selection in the drop-down menu, some fields might be mandatory and specified in red.
   Note: Changing these properties within this table or the Authentication type invalidates the connection you might have already
   created within Connector Builder. There is only one connection during design time, and it needs to be set up and tested against
   the latest authentication configuration.
   If you update your authentication settings, existing connections will fail. You must create a new connection and update your
   processes to use the new connection.
3. The Authentication screen is automatically generated based off the configuration you provided. The configuration displayed
   within Connector Builder is exactly the end-result that users of your activity package will see.  

   ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-337331-bff215e9.webp)

## Authentication table configuration

Disregarding the **Authentication type**, the loaded properties table identifies two items:

1. Fields available for any user within the authentication screen.
2. How authentication is handled by the authentication framework.

* Every line item in the table represents a property that can or can not be overwritten by the user. To present a given field
  on screen, it needs to be flagged as **Ask the user - Yes**.
* Every line item has a **Name** and a **Display name**. The **Name** is what the vendor is expecting for the technical setup and the latter is of importance on how to ask this input from the
  user on the authentication screen.
* Every line item holds an action menu which allows editing the property into far more detail. This is where you can state that
  a given property needs to be sent as a header. Refer to the [API Key](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/authentication-configuration#api-key) section for more examples.

## Authentication types

In the **Authentication** tab, you configure the authentication type for your connector. The following options are supported:

* OAuth 2.0 Authorization code
* OAuth 2.0 Authorization code with PKCE
* OAuth 2.0 Client credentials
* Basic
* API key
* Personal Access Token (PAT)
* Custom
* No authentication

:::note
When setting up the authentication, you are configuring how anybody using your
connector needs to authenticate. This is you while you are building the connector,
but could also be others that end up using your creation.
:::

### OAuth 2.0 Authorization code

#### Overview

OAuth 2.0 authorization code is one of the most
commonly used authentication protocols.

#### Authentication fields

URL fields such as Authorization URL and Token URL
do not inherit the base URL from the connector and require the
entire URL. This allows for use cases where a provider uses a
different base URL for authentication than that of the rest of the
API.

#### Required fields

:::note
The client ID and
client secret are often generated from the API provider.
Please reference the provider’s documentation to learn how
to generate these values for authentication.
:::

| Field | Description |
| --- | --- |
| **Client ID** | Provider-generated application identifier. |
| **Client secret** | Provider-generated application secret key. |
| **Authorization URL** | URL that redirects the user to complete the authentication process. Returns a authorization code. |
| **Token URL** | URL that UiPath uses to exchange the authorization code for a token. |

#### Additional fields

| Field | Description |
| --- | --- |
| **Scope** | Add necessary scopes for a connector with a space separating each scope (i.e., `read write openid`). |
| **Refresh token URL** | URL needed to generate a new access token if a refresh token is also returned. This is often the same URL that is used for **Token URL**. |
| **Token Revoke URL** | URL needed to revoke the access token. |
| **Refresh interval** | How long the access token is valid. The default value is 3600 seconds or 60 minutes. |
| **Connection name** | The name of the connection in UiPath once authentication is completed. |
| **Basic Header** | Indicates whether the client ID and secret are sent as a Base64-encoded value in the `Authorization` header. Boolean value (true/false); default is true. |

#### How it works

Once all the field values are added or configured
for the connector, UiPath®
automatically guides you through the necessary steps to complete the
authentication flow. UiPath supports the protocol and, if provided
with a Refresh token URI, automatically regenerates access tokens in
the background as needed. This keeps the connection alive and
functional for as long as the underlying refresh token is
valid.

#### Post-authorization request format

After the initial configuration is complete
and a connection is made, all requests made for that connector have the
authorization header automatically included in the
request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {yourToken}'
```

### OAuth 2.0 Authorization code with PKCE

#### Overview

OAuth 2.0 authentication code with PKCE (Proof Key for Code Exchange) is a common
authentication protocol that is leveraged largely by single page applications,
applications that cannot securely store a Client Secret or applications that cannot
ensure secure retrieval of an authorization code.

#### Authentication fields

URL fields such as Authorization URL and Token URL do not inherit the base URL from
the connector and require the entire URL. This allows for use cases where a provider
uses a different base URL for authentication than that of the rest of the API.

#### Required fields

:::note
The client ID and client secret are often generated from the
API provider. Please reference the provider’s documentation to learn how to generate
these values for authentication.
:::

| Field | Description |
| --- | --- |
| **Client ID** | Provider-generated application identifier. |
| **Client secret** | Provider-generated application secret key. |
| **Authorization URL** | URL that redirects the user to complete the authentication process. Returns a authorization code. |
| **Token URL** | URL that UiPath uses to exchange the authorization code for a token. |

#### Additional fields

| Field | Description |
| --- | --- |
| **Scope** | Add necessary scopes for a connector with a space separating each scope (i.e., `read write openid`). |
| **Refresh token URL** | URL needed to generate a new access token if a refresh token is also returned. This is often the same URL that is used for **Token URL**. |
| **OAuth2 PKCE Code Challenge Method** | The method used to generate the challenge. Can be either `S256` or `plain` (recommended: `S256`). |
| **Token Revoke URL** | URL needed to revoke the access token. |
| **Refresh interval** | How long the access token is valid. The default value is 3600 seconds or 60 minutes. |
| **Connection name** | The name of the connection in UiPath once authentication is completed. |
| **Basic Header** | Indicates whether the client ID and secret are sent as a Base64-encoded value in the `Authorization` header. Boolean value (true/false); default is true. |

#### How it works

Once all the field values are added or configured for the connector, UiPath® automatically you through the necessary
steps to complete the authentication flow. UiPath supports the protocol and, if
provided with a Refresh token URI, automatically regenerates access tokens in the
background as needed. This keeps the connection alive and functional for as long as
the underlying refresh token is valid.

UiPath supplies the challenge string necessary for PKCE based authorization, only the
OAuth2 PKCE Code Challenge Method is required.

#### Post-authorization request format

After the initial configuration is complete and a connection is made, all requests
made for that connector have the authorization header automatically included in the
request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer {yourToken}',
```

### OAuth 2.0 Client credentials

#### Overview

OAuth 2.0 client credentials is a method for returning an access token granting access to protected resources using application
specific credentials which grant the permission necessary. Client credentials are often used for machine-to-machine (M2M)
applications and are not usually representative of user permissions.

#### Authentication fields

URL fields such as Token URL do not inherit the base URL from the connector and require the entire URL. This allows for use
cases where a provider uses a different base URL for authentication than that of the rest of the API.

#### Required fields

:::note
The client ID and client secret are often generated from the API provider. Please reference the provider’s documentation
to learn how to generate these values for authentication.
:::

| Field | Description |
| --- | --- |
| **Client ID** | Provider-generated application identifier. |
| **Client secret** | Provider-generated application secret key. |
| **Token URL** | URL used to retrieve the access token. |

#### Additional fields

| Field | Description |
| --- | --- |
| **Scope** | Add necessary scopes for a connector with a space separating each scope (i.e., `read write openid`). |
| **Refresh interval** | How long the access token is valid. The default value is 3600 seconds or 60 minutes. |
| **Connection name** | The name of the connection in UiPath once authentication is completed. |
| **Basic Header** | Indicates whether the client ID and secret are sent as a Base64-encoded value in the `Authorization` header. Boolean value (true/false); default is true. |

#### How it works

Once all the field values are added or configured for the connector UiPath® generates an authorization request, passing through the necessary credentials to generate an access token. Since OAuth 2.0
client credentials is meant for machine-to-machine (M2M) applications, you only get the initial UiPath authorization page
and will have no further redirects.

Once a successful authorization flow is detected, UiPath maintains the connection as long as the provided credentials are
valid.

#### Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the authorization
header automatically included in the request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer {yourToken}',
```

### Basic authentication

#### Overview

The basic authentication type allows you to define a username and password that are
then Base64-encoded and prefixed with `Basic`. The username and
password, which can be modified, are used in all connector requests as the value for
the Authorization header.

#### Authentication fields

| Field | Description |
| --- | --- |
| **Username** | The first value in the two-part colon delineated and Base64-encoded `Authorization` header value. |
| **Password** | The second value in the two-part colon delineated and Base64-encoded `Authorization` header value. |
| **Connection name** | The name of the connection in UiPath once authentication is completed. |

#### How it works

When provided with the username and password values, UiPath® combines and colon-separates the values, Base64-encodes them, and
prefixes `Basic` to generate an `Authorization` header
value (e.g. `Authorization: Basic base64(username:password)`). This
header value is passed into each request as a means of authentication.

#### Post-authorization request format

After the initial configuration is complete and a connection is made, all requests
made for that connector have the authorization header automatically included in the
request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Basic base64(username:password)'
```

### API key

#### Overview

Some providers offer an API key as a form of authentication to access their API resources. In Connector Builder, this authentication
type results in the use of an `'X-Acess-Token: <provider_api_key>'` header that is passed into connector requests.

#### Authentication fields

| Field | Description |
| --- | --- |
| **API key** | The API key generated from the API provider to be used as the value for the `X-Access-Token` header on all connector requests. |
| **Connection mame** | The name of the connection in UiPath once authentication is completed |

#### How it works

When you use the provider-generated API key value for the API Key parameter in Settings- Authentication, every request made
for that connector includes an `X-Access-Token` header with the API key provided as the header value.

#### Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the `X-Access-Token` header automatically included in the request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'X-Access-Token: {yourtoken}'
```

### Personal Access Token

#### Overview

Some providers provide non-expiring access tokens and use the `Authorization:
{access_token}` header pattern for authenticating requests. The PAT
authentication method allows you to provide the necessary access token and applies
the headers previously listed but does not maintain the access token if it expires
at any point.

#### Authentication fields

| Field | Description |
| --- | --- |
| **Personal access token** | The provider-generated access token to be used as a value in the `Authorization` header field on all connector requests. Field defaults to prefix the token with `Bearer` to accommodate the common bearer authentication pattern. |
| **Connection name** | The name of the connection in UiPath once authentication is completed. |

#### How it works

When you use the provider-generated API key value for the `Personal Access`Token parameter in Settings- Authentication, every request made for that
connector includes an `X-Access-Token` header with the Personal
access token provided as the header value.

#### Post-authorization request format

After the initial configuration is complete and a connection is made, all requests
made for that connector have the `Authorization` header automatically
included in the
request.

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: {personal_access_token}'
```

### Custom

#### Overview

Custom authentication should be used when the vendor configuration does not follow
any of the standards but does require authentication details to be exchanged and
sent on every request.

#### Authentication fields

The Custom authentication fields come with an `Authorization`
parameter as an example field but can be customized to match the authentication
patterns of the API provider.

Any parameters added to the authentication from Custom authentication apply to the
connector's requests.

:::note
For now, Custom authentication does not allow you to
create a custom authentication flow. It lets you customize the standard
authentication parameters applied to requests within the connector.
:::

#### How it works

Parameters added to the authentication section are automatically included in any
connector requests.

### No authentication

The **No authentication** option provides a quick selection from the listing and
deletes all properties from the authentication configuration table.

#### How to use it

Use this option if the vendor application you are connecting to is available without
having to sign in. This can be an online public service or an API that is exposed
internally within the company. It requires no headers to be sent on any requests
identifying who is making the API call.

**Outcome when sending a
request**

```
curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```