> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> User management and authentication options for the API connector.

## Users and Authentication

Arc uses OAuth 2.0 and authtoken-based authentication to control per-user access to the API.

Authtokens are unique, randomly generated identifiers that users authenticate to an API with. Authtokens also represent the user's current permissions. Authtokens let you connect using any of the major authentication schemes. For example, to use HTTP Basic authentication, set the username in the User header and the user's corresponding authtoken in the Password header. See [Authentication](#authentication) for more information on authenticating to the API.

OAuth 2.0 provides a more structured authentication flow for clients that need to manage token lifecycles or integrate with external applications. Arc supports the Client Credentials grant type, which is intended for server-to-server integrations where no user interaction is required. Rather than authenticating directly with a static authtoken, OAuth 2.0 clients obtain a short-lived access token by presenting their client credentials to the Access URL.

### Adding Users

To add a user, navigate to the **Users** tab for the connector, and click **Add**. In the **Settings** dialog, enter the following information:

| Field          | Description                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**       | Enter a username to be used in HTTP authentication.                                                                                                                            |
| **Active**     | Indicate whether the user is active or inactive.                                                                                                                               |
| **Operations** | Select the HTTP methods the user is allowed to access: GET, POST, PUT/PATCH/MERGE, or DELETE. These correspond to SELECT, INSERT, UPDATE, and DELETE statements, respectively. |

Click the **Authentication** tab to add details on authtokens and OAuth 2.0.

| Field                           | Description                                                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authtoken**                   | The system-generated authtoken. Make sure to copy it to a safe location before saving the user, because it is not shown again.                    |
| **Maximum Requests per Hour**   | Uncheck **Unlimited Requests** to set a limit on the maximum requests per hour for this user.                                                     |
| **Maximum Concurrent per Hour** | Uncheck **Unlimited Requests** to set a limit on the maximum number of requests that can be sent simultaneously.                                  |
| **Grant Type**                  | The OAuth 2.0 grant type that determines how the client application obtains an access token. **Client Credentials** is currently the only option. |
| **Client Id**                   | The system-generated client Id token.                                                                                                             |
| **Client Secret**               | The system-generated client secret. Make sure to copy it to a safe location before saving the user, because it is not shown again.                |
| **Access URL**                  | The endpoint URL used by the client application to request an access token using the configured credentials.                                      |

<Note>
  User-specific settings override server-wide API limit settings. An empty value for one of the user settings uses the server default.
</Note>

### Configuring the User Database

Arc stores user information in an SQLite database by default. You can also save user information to the database of your choice. If you are using the embedded server, specify the connection string to the caching database in the `connectionStrings` element of the Web.config file. Otherwise, refer to the documentation for the server you are hosting the application on.

## Authentication

Users access API resources by providing authtokens with requests. You can manage users, authtokens, and OAuth 2.0 credentials on the [Users](./api-config#users-tab) configuration tab.

Before users can call the API, you also need to set trusted IP addresses for connections. These settings are available on the [Server](./api-config#users-tab) configuration tab. By default, all IP addresses are restricted.

### Using Authtokens in Basic Authentication

Enter the user's authtoken as the password when using Basic Authentication.

### Using Auth Tokens in the HTTP Header

Add the HTTP header `x-cdata-authtoken` with the desired authtoken as part of the HTTP request.

### Using Authtokens as Query String Parameters

To allow the connector to pass the authtoken in query string parameters, open the **Server** tab of the API connector settings pane and select **Allow authtoken in URL** in the **Advanced Settings** section.

After enabling this feature, you can specify the authtoken as the value of the `@authtoken` parameter, which can be supplied as part of the HTTP form-post data or a query parameter.