--- title: "Configuration" slug: "relativity-configuration" updated: 2026-09-08T19:52:50Z published: 2026-09-08T19:52:50Z canonical: "help.agilityblue.com/relativity-configuration" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.agilityblue.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration ## Choose an Authentication Method Agility Blue offers two authentication methods to connect to Relativity: Basic or OAuth2 | Authentication Method | Description | | --- | --- | | **Basic** | Requires you to enter a Relativity username and password in order to access Relativity resources. Relativity account information is stored on the Agility Blue servers in an encrypted format. | | **OAuth2** Recommended | Requires you to create an OAuth2 client within Relativity using the `Client Credentials` OAuth2 flow. Relativity OAuth2 information is stored on the Agility Blue servers in an encrypted format. | > [!NOTE] > Our recommendation > > The OAuth2 authentication method is our recommended approach. There is additional setup involved on the Relativity side, but the benefit is that you do not have to expose any username or password information to Agility Blue in order to communicate with Relativity. ## Relativity Permissions Regardless of the chosen authentication method, it is necessary that the linked Relativity user account has enough permissions to be able read a list of Relativity Workspaces and have the ability to read Relativity Production Sets within a workspace. ### RelativityOne Usage Report Metrics To allow Agility Blue the ability to collect usage report metrics from a RelativityOne instance, Relativity requires the following: - You must use the `OAuth2` authorization method to connect to Relativity - The connected Agility Blue account must be a `System Administrator` or a `Client Domain Administrator` - The connected Agility Blue account must have the `View Usage Report` instance permission - The connected Agility Blue account must have the `View Admin Repository` permission These requirements are set by Relativity and are outlined under their [usage reports documentation](https://help.relativity.com/RelativityOne/Content/Management_Console/Usage_Reports.htm#Permissions). For more information on setting up RelativityOne instance permissions, please refer to their [help documentation on setting instance permissions](https://help.relativity.com/RelativityOne/Content/Relativity/Security_permissions/Setting_instance_permissions.htm) or contact Relativity support for assistance. ## Configure Relativity Authentication > [!NOTE] > Relativity documentation > > For more information on how Relativity leverages basic and bearer (OAuth2) authentication, refer to [Relativity’s API authentication documentation](https://platform.relativity.com/RelativityOne/Content/REST_API/REST_API_authentication.htm). ## Configure Relativity for Basic Authorization If you choose to use the Basic Authorization method to connect to Relativity from Agility Blue, there is not much setup needed from Relativity. We recommend that a dedicated Relativity user account be created specifically for Agility Blue for access control and auditing purposes — however, this is not necessary. The Relativity user account must be setup with a `Password Authentication Provider`, as you will need to provide the Relativity username and password to Agility Blue. ## Configure Relativity for OAuth2 Authorization (Recommended) Login to Relativity as a user that has permission to create OAuth2 Clients. Navigate to the `OAuth2 Client` tab (this can be found under the `Authentication` parent tab). ![Menu options showing Authentication and OAuth2 Client selection in a management console.](https://cdn.document360.io/630eeab5-df61-41eb-8d61-d3488c45f27d/Images/Documentation/Configuration 1 png.png) Click on the `New OAuth2 Client` button and you will be presented with the following page: ![](https://cdn.document360.io/630eeab5-df61-41eb-8d61-d3488c45f27d/Images/Documentation/Configuration 2 png.png) Fill out the OAuth2 Client Information form with the following information: - **Name**: Agility Blue - **Flow Grant Type**: Client Credentials - **Context User**: Select a user that will be represented by calls from Agility Blue. We recommend that a dedicated Relativity user account be created specifically for Agility Blue for access control and auditing purposes, though not necessary. - **Enabled**: Yes - **Access Token Lifetime**: Relativity recommends setting this value to 60 (1 hour). This means that when Agility Blue receives an OAuth2 token from Relativity, the token will be valid for one hour before Agility Blue needs to ask Relativity for a new token. When you save the form, Relativity will display the **OAuth2 client details**. Pay attention to the two fields that Relativity generates on this screen: `Client Id` and `Client Secret`. You will need to provide these values to Agility Blue while configuring the connection information. ## Configure Agility Blue Within an Agility Blue workspace, navigate to the workspace settings page by clicking on the gear icon in the top right and choosing the `Settings` option. Click on the integrations section tab on the left to view the list of installed integrations. Locate the `Relativity` integration. If the toggle switch on the far right is switched off, click on it to enable it. If the toggle switch is already enabled, click on the cog icon button to the left of the switch. If you do not see the Relativity Integration listed, please contact support to get one installed into your workspace. ![Workspace settings showing integrations with Relativity and connection options highlighted.](https://cdn.document360.io/630eeab5-df61-41eb-8d61-d3488c45f27d/Images/Documentation/Configuration 3 png.png) After clicking on the cog icon button, you will be presented with the following window: ![Configuration settings for Relativity integration, including OAuth2 client details and URL.](https://cdn.document360.io/630eeab5-df61-41eb-8d61-d3488c45f27d/Images/Documentation/Configuration 4 png.png) Fill out the form with the following information - **Relativity Instance URL** This is the base URL for your Relativity instance. For example: `https://agilityblue.relativity.one`. It is highly recommended that your Relativity Instance URL is configured as HTTPS to ensure secure communication between Agility Blue and Relativity. - **Relativity Authorization Method** Choose the authorization method you would like Agility Blue to use to communicate with Relativity. - If you choose the `Basic` authorization method, the following fields become visible: - **Relativity Username** Enter a Relativity username. - **Relativity Password** Enter the password for the Relativity user - If you choose the `OAuth2` authorization method, the following fields become visible: - **Relativity OAuth2 Client Id** Enter the OAuth2 Client Id that Relativity provided during the OAuth2 Client setup instructions above. - **Relativity OAuth2 Client Secret** Enter the OAuth2 Client Secret that Relativity provided during the OAuth2 Client setup instructions above. - If your Relativity instance URL is not a RelativityOne instance, you will see a **Use Modern Relativity APIs?** switch Disable this switch if your version of Relativity Server is lower than version 12.1.431.2 (this is uncommon). - Click on the `Save` button After saving, Agility Blue will attempt to reach out to Relativity and test the connection. If Agility Blue is able to connect to your Relativity instance, a message will briefly display that a successful connection was made and the connected Relativity version. If you receive an error, make sure that your settings are correct and the account you are using in Relativity has the proper permissions setup. Contact support at support@sadiebluesoftware.com to receive troubleshooting assistance on connection issues.