Relativity User Management API Guide

Auth method: OAuth 2.0 (client credentials grant) - Bearer token passed in Authorization header. Basic authentication (username:password Base64) is also supported for legacy integrations but deprecated for RelativityOne.

Setup steps

1. In RelativityOne, navigate to the OAuth2 Clients tab under Authentication.
2. Create a new OAuth2 Client with grant type 'Client Credentials'.
3. Note the Client ID and Client Secret.
4. POST to https://{instance}.relativity.one/Relativity/Identity/connect/token with grant_type=client_credentials, client_id, client_secret, and scope=SystemUserRead SystemUserWrite (or relevant scopes).
5. Use the returned access_token as a Bearer token in the Authorization header for all subsequent API calls.

Required scopes

Create User

• Method: POST
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Users/workspace/-1/users
• Watch out for: Workspace ID -1 denotes the admin-level (system) context. Client ArtifactID must be a valid existing client.

Request example

POST /Relativity.REST/api/Relativity.Users/workspace/-1/users
Authorization: Bearer {token}
Content-Type: application/json
{
  "userRequest": {
    "FirstName": "Jane",
    "LastName": "Doe",
    "EmailAddress": "jane.doe@example.com",
    "Type": {"Value": "Internal"},
    "Client": {"ArtifactID": 1015644}
  }
}

Response example

{
  "ArtifactID": 1234567
}

Read User

• Method: GET
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Users/workspace/-1/users/{userArtifactID}
• Watch out for: ArtifactID must be known in advance; use the query endpoint to look up users by email.

Request example

GET /Relativity.REST/api/Relativity.Users/workspace/-1/users/1234567
Authorization: Bearer {token}

Response example

{
  "ArtifactID": 1234567,
  "FirstName": "Jane",
  "LastName": "Doe",
  "EmailAddress": "jane.doe@example.com",
  "Type": {"Value": "Internal"},
  "LastLoginDate": "2024-11-01T10:00:00Z"
}

Update User

• Method: PUT
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Users/workspace/-1/users/{userArtifactID}
• Watch out for: Full object replacement semantics may apply; omitting fields can reset them. Verify field behavior in docs before partial updates.

Request example

PUT /Relativity.REST/api/Relativity.Users/workspace/-1/users/1234567
Authorization: Bearer {token}
Content-Type: application/json
{
  "userRequest": {
    "FirstName": "Janet"
  }
}

Response example

HTTP 200 OK
{}

Delete User

• Method: DELETE
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Users/workspace/-1/users/{userArtifactID}
• Watch out for: Deleting a user is permanent. Users with active workspace assignments may need to be removed from groups/workspaces first.

Request example

DELETE /Relativity.REST/api/Relativity.Users/workspace/-1/users/1234567
Authorization: Bearer {token}

Response example

HTTP 200 OK
{}

Query Users (Object Manager)

• Method: POST
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.ObjectManager/v1/workspaces/-1/objects/query
• Watch out for: ArtifactTypeID 2 corresponds to the User object type. Condition syntax is Relativity-specific query language, not SQL.

Request example

POST /Relativity.REST/api/Relativity.ObjectManager/v1/workspaces/-1/objects/query
Authorization: Bearer {token}
Content-Type: application/json
{
  "objectType": {"ArtifactTypeID": 2},
  "condition": "'Email Address' == 'jane.doe@example.com'",
  "fields": [{"Name": "*"}],
  "start": 1,
  "length": 25
}

Response example

{
  "TotalCount": 1,
  "Objects": [
    {"ArtifactID": 1234567, "FieldValues": [...]}
  ]
}

Add User to Group

• Method: POST
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Groups/workspace/-1/groups/{groupArtifactID}/users
• Watch out for: Group membership controls workspace access. Users must be added to workspace-level groups to gain access to specific workspaces.

Request example

POST /Relativity.REST/api/Relativity.Groups/workspace/-1/groups/9876543/users
Authorization: Bearer {token}
Content-Type: application/json
{
  "userArtifactIDs": [1234567]
}

Response example

HTTP 200 OK
{}

Remove User from Group

• Method: DELETE
• URL: https://{instance}.relativity.one/Relativity.REST/api/Relativity.Groups/workspace/-1/groups/{groupArtifactID}/users/{userArtifactID}
• Watch out for: Removing a user from all groups in a workspace effectively revokes their workspace access.

Request example

DELETE /Relativity.REST/api/Relativity.Groups/workspace/-1/groups/9876543/users/1234567
Authorization: Bearer {token}

Response example

HTTP 200 OK
{}

Get OAuth2 Token

• Method: POST
• URL: https://{instance}.relativity.one/Relativity/Identity/connect/token
• Watch out for: Tokens expire (typically 3600 seconds). Implement token refresh logic. Scopes must match those configured on the OAuth2 Client in Relativity admin.

Request example

POST /Relativity/Identity/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={clientId}
&client_secret={clientSecret}
&scope=SystemUserRead SystemUserWrite

Response example

{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

• Rate limits: Relativity does not publicly document specific rate limit thresholds or tiers in their official documentation as of the research date.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No explicit rate limit values, headers, or Retry-After behavior documented in official Relativity developer docs. Throttling behavior may exist at the infrastructure level for RelativityOne but is not publicly specified.

• Pagination method: offset

• Default page size: 10

• Max page size: 200

• Pagination pointer: start / length (used in Object Manager query requests as part of the request body payload)

• Webhooks available: No

• Webhook notes: Relativity does not document a native outbound webhook system for user lifecycle events in official developer documentation.

• Alternative event strategy: Use polling via the Object Manager query endpoint to detect user changes, or leverage Relativity's Event Handler framework (server-side .NET customization) for internal event-driven logic within the platform.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• No native SCIM 2.0 endpoint is documented in official Relativity or RelativityOne developer documentation.
• IdP-based provisioning (Okta, Entra ID) is not listed as natively supported via SCIM in official docs.
• User provisioning must be performed via the REST User Management API or manual admin processes.

Provisioning a new user requires two sequential API calls: POST to the Users endpoint to create the record (capturing the returned ArtifactID), then POST to the Groups endpoint to add the user to the target workspace group

user creation alone grants no access.

Looking up a user by email requires a POST to the Object Manager query endpoint with ArtifactTypeID=2 and a condition on the Email Address field using Relativity's proprietary condition syntax (not SQL);

the returned ArtifactID is then used for subsequent Users endpoint calls.

Deprovisioning is a multi-step process: query the user's current group memberships, issue a DELETE to the Groups endpoint for each group, and optionally issue a DELETE to the Users endpoint for permanent removal

there is no single disable call.

The Client field (object reference) must point to a valid existing client ArtifactID at user creation time;

this is a hard dependency that must be resolved before the create call.

Provision a new internal user and grant workspace access

1. POST to /Relativity.REST/api/Relativity.Users/workspace/-1/users to create the user with FirstName, LastName, EmailAddress, Type=Internal, and Client ArtifactID.
2. Capture the returned ArtifactID of the new user.
3. Identify the target workspace's group ArtifactID (query via Object Manager with ArtifactTypeID for Group).
4. POST to /Relativity.REST/api/Relativity.Groups/workspace/-1/groups/{groupArtifactID}/users with the new user's ArtifactID to add them to the workspace group.

Watch out for: The Client ArtifactID must exist before user creation. Group membership - not user creation alone - determines workspace access.

Look up a user by email address and retrieve their profile

1. POST to /Relativity.REST/api/Relativity.ObjectManager/v1/workspaces/-1/objects/query with objectType ArtifactTypeID=2 and condition filtering on 'Email Address' field.
2. Extract the ArtifactID from the query response.
3. GET /Relativity.REST/api/Relativity.Users/workspace/-1/users/{ArtifactID} to retrieve the full user profile.

Watch out for: The Object Manager query uses Relativity's proprietary condition syntax. Email field name in conditions must match the Relativity field display name exactly.

Deprovision a user by revoking all workspace access

1. Query the user's current group memberships via Object Manager (ArtifactTypeID for Group, filtering by user association).
2. For each group, DELETE /Relativity.REST/api/Relativity.Groups/workspace/-1/groups/{groupArtifactID}/users/{userArtifactID} to remove the user.
3. Optionally DELETE /Relativity.REST/api/Relativity.Users/workspace/-1/users/{userArtifactID} to permanently remove the user record if full deletion is required.

Watch out for: There is no documented 'disable' or 'deactivate' flag on the user object; access revocation is achieved by group removal. Full deletion is permanent and cannot be undone via API.

The split between the Users API and the Object Manager API is the primary integration trap: developers who attempt to query users via the Users endpoint directly will find no email-based search capability and must pivot to Object Manager with the non-obvious ArtifactTypeID=2.

URL versioning is inconsistent across service areas - Object Manager uses /v1/ in the path while the Users endpoint does not, and assuming a uniform versioning pattern will produce 404s. OAuth2 scope misconfiguration is silent at token issuance but fails at the API call level;

scopes must be explicitly granted on the OAuth2 Client record in admin before they appear in token responses. The absence of documented rate limits is a reliability risk - undocumented infrastructure-level throttling may exist, and integrations without backoff logic will fail unpredictably under load.

The lack of a deactivation flag means any integration that models disable user as a single API call must be redesigned around group removal, which requires enumerating memberships first.