Last date modified: 2026-Nov-16

Relativity REST API authentication

The Relativity REST APIs support multiple authentication methods so that you can choose the best one for your environment and application requirements. To provide secure communication between a client and a Relativity endpoint, it supports cookie authentication and bearer token authentication.

An authentication header is required for all calls to the REST endpoint.

The Authorization field in the HTTP header is used to pass user credentials. When authentication fails, the error code 401 (Unauthorized) is returned with additional information in the WWW-Authenticate header of the response.

If a request doesn't include an authentication header, the error code 401 is returned with the header: Bearer realm="Relativity.REST". If you set DeveloperMode instance setting is set to True, this error isn't returned.

See the following related page:

Cookie authentication

When a user logs into Relativity, the RelAuth cookie is issued to the browser. This encrypted cookie contains the information that validates the user. This cookie can be passed to REST service call instead of an HTTP authorization header. If the encrypted cookie is valid, the call will be authenticated under the credentials of the user who logged in via the web.

Applications that use custom pages often call REST services: a typical example can be a custom page that makes AJAX calls to a REST endpoint. The RelAuth cookie is automatically added to any AJAX calls from the browser. This enables most custom page applications to simply make their AJAX calls to the REST service and "piggy-back” on top of the browser’s authentication that is automatically handled by Relativity. For more information about custom pages, see Customize the UI.

Cookie authentication from JavaScript

You don't need to include an additional Authorization header when using cookie authentication from JavaScript within Relativity. The browser performs the authentication. See the following code sample:

Copy
<script type = "text/javascript" >
  $(document).ready(function() {
  $.ajax({
    url: "http://localhost/Relativity.REST/Relativity-Identity/v1/workspaces/-1/users",
    type: "GET",
    contentType: "application/json"
  })
    .done(function(data) {
    alert("success");

    var userCount = data.ResultCount;
    var retVal = "userCount: " + userCount;
    $("#result").text(retVal);
  })
    .fail(function(xhr, status, error) {
    alert("Status: " + status);
    alert("Error: " + error);
    alert("ResponseText: " + xhr.responseText);
  })
    .always(function() {
    alert("complete");
  });
});

Bearer token authentication

Bearer Token Authentication

You can connect to the REST services using bearer token authentication. When using bearer token authentication, clients access the service with an access token issued by the Relativity identity service based on a consumer key and secret obtained through an OAuth2 client.

When multiple web servers are hosted behind a load balanced route, you can't programmatically retrieve an authentication token. You must use a direct route to one of the web servers to retrieve the authentication token.

To create, obtain and use a bearer access token:

  1. Create a Relativity OAuth2 Client (for more information see OAuth2 clients on the Relativity aiR Documentation site):
    • Click Home > Authentication > OAuth2 Client Manager.
    • Click New OAuth2 Client to create a new client, or click Edit to modify an existing client.
    • Complete the fields on the form. Fields in orange are required:  
      • Name- enter a unique name for the OAuth2 client.
      • Enabled- indicate whether the client will have access to Relativity.
      • Flow Grant Type- select Client Credentials.
      • Context User- select a user with the appropriate level of permissions or group membership for the operations you want to perform. (Usually a member of the Relativity Administrators group, but could be different depending on the API or operation invoked).
      • Access Token Lifetime- set the duration (in minutes) for which access tokens are valid. The recommended value is 60 minutes.
    • Click Save to create the OAuth2 client. For more information, see OAuth2 clients on the Relativity aiR Documentation site.
  2. Obtain a Bearer Token by sending a POST request to the token endpoint with your credentials.
    Copy
    curl -X POST "<host>/Relativity/Identity/connect/token" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d "grant_type=client_credentials" \
         -d "scope=SystemUserInfo" \
         -d "client_id=<your_client_id>" \
         -d "client_secret=<your_client_secret>" \
  3. Use the Bearer Token by including the token in the Authorization header of your API requests.
  4. Copy
    curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
         -H "Authorization: Bearer <your_access_token>"

Bearer Access tokens in PowerShell

You can use the following sample script to authenticate and retrieve an access token with PowerShell

Copy
Obtaining a Bearer Token in PowerShell
# Set Variables (replace with appropriate values from your environment)
$relativityHost = "<host>"
$clientId = "XXX"
$clientSecret = "XXX"

# Define headers, Uri and body for authentication
$tokenHeaders = @{
    'Content-Type' = 'application/x-www-form-urlencoded'
}
$tokenUri = "$relativityHost/Relativity/Identity/connect/token"
$tokenBody = "grant_type=client_credentials&client_id=$clientId&client_secret=$clientSecret&scope=SystemUserInfo"

# Request Access Token
$accessToken = Invoke-RestMethod -Uri $tokenUri -Headers $tokenHeaders -Body $tokenBody -Method POST

# Extract the token (only the access token, not the full response)
$token = $accessToken.access_token

You can then use the token in a request, see the example below (replacing the placeholders with the values of the service you are interacting with)

Copy
Using the token in a request
$requestHeadersToUse = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}

# set the endpoint and method type
$requestUri = "$relativityHost/api/<servicename>/<version>/<endpoint>"
$methodType = "GET"

# send the request and get the reponse 
$response = Invoke-RestMethod -Uri $requestUri -Method $methodType -Headers $requestHeadersToUse

# do something with the response
$response | ConvertTo-Json

Choose a scope for your access token

When you request an access token from the Relativity identity service, the scope parameter determines what the token contains. The scope you request determines whether the access token includes the Relativity/resources audience (aud claim) that Relativity.REST and Kepler services require. A token without that audience is rejected with a 401 (Unauthorized) response, even though the identity service issued the token successfully.

Scope What it does When to use it
openid Requests an ID token that identifies the signed-in user (sub claim). Include it with every Authorization Code request.
UserInfo An identity scope. It adds the signed-in user's details, such as user Artifact ID, username, first name, and last name, to the ID token. The access token it produces does not include the Relativity/resources audience, so Relativity.REST and Kepler services reject it. Identify the user. Do not rely on it alone to call Relativity.REST or Kepler services.
UserInfoAccess A resource scope. It includes the same user details in the access token and adds the Relativity/resources audience, so Relativity.REST and Kepler services accept the token. Request it, together with openid, when you call Relativity.REST or Kepler services on behalf of a signed-in user (Authorization Code flow).

For example, request the following scopes in an Authorization Code request:

Copy
scope=openid UserInfoAccess

If you request openid UserInfo with the Authorization Code flow, the token request succeeds, but calls to Relativity.REST return 401 (Unauthorized). Request UserInfoAccess instead.

Troubleshoot a 401 response for a valid token

If Relativity.REST returns 401 (Unauthorized) for an access token that the identity service issued, check the token's audience:

  1. Decode the payload of the access token. For example, paste the token into a JWT decoder, or Base64-decode the second segment of the token.
  2. Check that the aud claim is present and includes Relativity/resources.
  3. If the aud claim is missing, request a new token with the UserInfoAccess scope.

Treat access tokens as credentials. Don't paste production tokens into public or untrusted decoding tools.

Authorization Code with PKCE (delegated user access)

Use the Authorization Code flow with Proof Key for Code Exchange (PKCE) when your application needs to call Relativity.REST on behalf of a signed-in user. API calls run with that user's own Relativity permissions. By comparison, a Client Credentials client runs as the Context User that you assign to the OAuth2 client, regardless of who is using your application.

To get and use a token with the Authorization Code flow:

  1. Create a Relativity OAuth2 client as described in the previous section, with the following differences:
    • Flow Grant Type - select Code.
    • Redirect URIs - enter the URL in your application that receives the authorization response. The redirect URI in each request must match a registered value.
  2. Generate a PKCE code verifier and S256 code challenge for the request.
  3. Send the user to the authorization endpoint, requesting the openid and UserInfoAccess scopes. See Choose a scope for your access token.
    Copy
    GET <host>/Relativity/Identity/connect/authorize
        ?response_type=code
        &client_id=<your_client_id>
        &redirect_uri=<your_redirect_uri>
        &scope=openid UserInfoAccess
        &code_challenge=<code_challenge>
        &code_challenge_method=S256
        &state=<state_value>
  4. The user signs in to Relativity, and Relativity redirects the browser to your redirect URI with an authorization code.
  5. Exchange the authorization code for an access token by sending a POST request to the token endpoint, including the code verifier. Confirm the token request parameters.
    Copy
    curl -X POST "<host>/Relativity/Identity/connect/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=authorization_code" \
      -d "client_id=<your_client_id>" \
      -d "code=<authorization_code>" \
      -d "redirect_uri=<your_redirect_uri>" \
      -d "code_verifier=<code_verifier>"
  6. Include the access token in the Authorization header of your requests, as you would for a Client Credentials token:
    Copy
    curl -X POST "<host>/Relativity.REST/API/Relativity.ObjectManager/v1/workspace/-1/object/queryslim" \
      -H "Authorization: Bearer <your_access_token>" \
      -H "Content-Type: application/json" \
      -d "<request_body>"

If Relativity.REST returns 401 (Unauthorized) for a token that the identity service issued, make sure that you requested the UserInfoAccess scope. See Choose a scope for your access token.

Feedback