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.

See the following related page:

• Identity (authentication and user accounts)

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<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.
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

# 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)

$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