REST API authentication

The Relativity REST API provides you with the ability to choose an authentication method that best fits your environment and application requirements. To provide secure communication between a client and the Relativity service endpoint, it supports basic authentication over HTTPS and Active Directory 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.

Note: If a request doesn't include an authentication header, the error code 404 is returned unless the DeveloperMode instance setting is set to True. For more information, see Set up your development environment.

This page contains the following information:

Basic authentication

When using basic authentication over HTTPS, you should send authentication credentials with every request to the REST API, since the service doesn't include an explicit login method or track a session token.

To include credentials in the HTTP header, you must supply a username and password that are concatenated into a string, using the format username:password. You must also compute the Base64 encoding for this string. The following code sample illustrates this process:

public void SetAuthorizationHeader(string username, string password, HttpClient request)
     string usernamePassword = string.Format("{0}:{1}", username, password);
     string base64usernamePassword = Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));
     request.DefaultRequestHeaders.Add("Authorization", "Basic " + base64usernamePassword);

A request includes the basic authentication header with the Authorization field followed by the word Basic (indicating the type of authentication), and the encoded user credentials:

Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=     

When authentication fails, the error code 401 (Unauthorized) is returned, and the header includes the message:

WWW-Authenticate: Basic realm="Relativity.REST"        

For more information about required HTTP header fields, see HTTP headers and Supported HTTP methods.

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 the Relativity’s REST APIs 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 Relativity APIs: a typical example can be a custom page that makes AJAX calls to a REST API. 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 APIs 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.

Active Directory authentication

You can use Active Directory authentication with the REST API by setting AuthenticationData for users through the Relativity UI. For more information, see Fields on the Users page of the Relativity 9.5 Documentation site.

After configuring AuthenticationData in Relativity, follow the same process for sending credentials as that used by basic authentication. Compute the Base64 encoding for the username and Active Directory password, and add this string to the Authorization header.

Note: Active Directory authentication uses Basic as the authorization method in the HTTP header.

Bearer token authentication

We are providing the bearer token authentication functionality as a preview so that you can evaluate it and provide us with feedback. The preview release offers a functional API, which will continue to undergo contract changes and further enhancements. Feedback >>

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

To get an access token:

  1. Create a Relativity OAuth2 client:
    • OAuth2 Flow must be Client Credentials.
    • The context user must be a member of the Relativity Administrators group.

    For more information, see OAuth2 clients on the RelativityOne Documentation site. You can also interact with OAuth2 clients programmatically.

  2. Make a POST request to the following URL:

    The request content type must be x-www-form-urlencoded.

    The request must include these parameters:

    • client_id – the ID of the OAuth2 client.
    • client_secret – The secret of the OAuth2 client.
    • scopeSystemUserInfo.
    • grant_typeclient_credentials.

    This is a cURL example of a token request :

    curl -X POST \ \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'client_id=t348bff173b12ok36d6d5ab80id&client_secret=69f2c71d25e464fba614e19fcc1430d5b256b7a2&scope=SystemUserInfo&grant_type=client_credentials'

    The response returns a token that can be used for accessing the Invariant Monitoring API.

        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiNotyEt1dCI6Ik9SZVo2SFE4SlM2aXBVWjJ5cDFNOGhUMVhRYyIsImtpZCI6Ik9SZVo2SFE4SlM2aXBVWjJ5cDFNOGhUMVhRYyJ9.eyJpc3MiOiJSZWxhdGl2aXR5IiwiYXVkIjoiUmVsYXRpdml0eS9yZXNvdXJjZXMiLCJleHAiOjE1MzQwNjkzNTgsIm5iZiI6MTUwMzMzNDk1OCwiY2xpZW50X2lkIjoiZTM4YmZmMTczYjEyZmIzNmQ2ZDVhYjgwY2QiLCJyZWxfdWFpIjoiOSIsInJlbF91Zm4iOiJSZWxhdGl2aXR5IiwicmVsX3VsbiI6IkFkbWluIiwicmVsX3VuIjoicmVsYXRpdml0eS5hZG1pbkBrY3VyYS5jb20iLCJvcl9sYiI6IlRydWUiLCJyZWxfaW5zIjoiQjgwNENDMzQtMUJBNS00NDZBLTkyMDItNTdFMTcwOUJCRDZDIiwic2NvcGUiOiJTeXN0ZW1Vc2VySW5mbyIsInJlbF9vcmlnaW4iOiIxOTIuMTY4LjEzNy4xIn0.DDgpxj8IlA7bhssU_RTWfL4qh53UrgaPR99UYk5pBTpp1f7gC0zIViLFT5oXREH9AZOlz7u29qDMv6M1GC0zNud1b6wdSWzSIObKohTjBnbzXW5cXYPIgp6qWZSmYV3TpnBUz1QtVCSY46h6yt9-eL81My40JI2OFYpkTwtEIBgCvdSAT5CQ-_M2U6ODp6CcOQ8LyGnGlZ18Ao11XCNhIBv3NDQHRGJL9qSLJ20NqigsXLoCINaS4Jp5JQBtCdyboKCYcXbJOVqPNtSyku2H4RhRAkJ0CsUJcwAf7FIoj0ZQVkvr2LvU99rmNCCPPl-0hJYikxBeVJ3-mc28Vu-1NA",
        "expires_in": 30734400,
        "token_type": "Bearer"