Workspace Service API

This guide will help you get started with the Workspace Service API, including making your first requests, understanding the available endpoints, and authenticating your API calls.

Guidelines for the Workspace Service API

Review the following guidelines for working with this API.

URLs

The URLs for the REST API endpoints include a path parameter {version} that you need to set before making a call:

1
<host>/api/workspace-service/{version}/workspace/{workspaceId}/state

• Replace {version} with the API version you want to use. For example, v1.

1
<host>/api/workspace-service/v1/workspace/{workspaceId}/state

RelativityOne REST API authentication

Overview

To access the Workspace Service API, you must authenticate your requests. RelativityOne supports two authentication methods:

• Cookie authentication
• Bearer token authentication

For more information on authentication methods, see Relativity REST API Authentication.

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.

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 RelativityOne 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 who is a member of the Relativity Administrators group.
     • 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 RelativityOne 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>"

Response codes

Workspace Service API uses conventional HTTP response codes to indicate the success or failure of an API request.

Generally:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided. For example, a required parameter was omitted.
• Codes in the 5xx range indicate an internal error with the Workspace Service API.

API endpoints

Get State

Permissions

To use the Get State endpoint, you need to either have the View Workspace permission for the workspace whose state you want to check or be a System Administrator or a Relativity Services user.

Calling the Get State endpoint

To retrieve the state of a workspace, send a GET request with a URL in the following general format:

1
<host>/api/workspace-service/v1/workspace/{workspaceId}/state

1
2
3
4
5
{
  "WorkspaceId":1010100,
  "State":"Active",
  "SetOn":"2024-08-27T17:23:26.737"
}

Possible states of a workspace

The possible workspace states are:

• None—the workspace exists, but has no assigned state.
• Creating—the workspace is in the process of being created.
• Active—the workspace is fully operational and available for use.
• ColdStorage—the workspace is in Cold Storage. It cannot be accessed unless it is retrieved.
• Errored—an error occurred. The workspace cannot be used.
• RecycleBin—the workspace has been moved to the Recycle Bin and is pending permanent deletion or restoration. Workspaces stay in the Recycle Bin for seven days, and they can be retrieved during that time.
• ScheduledForDeletion—the workspace is scheduled to be permanently deleted from the Recycle Bin. It cannot be retrieved.