API Authentication

Version 23.4.8800


API Authentication


Users

Arc uses auth token-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 for more information on authenticating to the API.

Adding Users

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

  • Name: Enter a username to be used in HTTP authentication.
  • Privileges: 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.
  • Max. Requests: Enter the maximum requests per hour for this user. A value of 0 allows the user unlimited access per hour.
  • Max. Concurrent Requests: Enter the maximum number of requests that can be sent simultaneously. A value of 0 allows the user unlimited simultaneous requests.

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

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 auth tokens with requests. You can manage users and auth tokens on the Users tab of the API Connector settings pane.

Before users can call the API, you also need to set trusted IP addresses for connections. These settings are available on the Server tab of the API Connector settings pane. By default, all IP addresses are restricted.

Using Auth Tokens in Basic Authentication

Enter the user’s auth token as the password when using Basic Authentication.

Using Auth tokens in the HTTP Header

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

Using Auth Tokens as Query String Parameters

To allow the connector to pass the auth token 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 auth token as the value of the @authtoken parameter, which can be supplied as part of the HTTP form-post data or a query parameter.