Permissions access control API

Relativity is modernizing the feature permission experience and the underlying model as features move to using role-based access control to improve security and flexibility. This model is powered by a public, versioned API, enabling organizations to manage access across Relativity products.

The transition to this new permissions approach will occur gradually, allowing for a smooth and organized migration from the current system.

Within Staging, the new API provides the ability to assign and revoke permissions at both the fileshare and tenant levels. These operations are performed through stable and extensible endpoints.

Guidelines for the permissions access control API

Review the following guidelines for working with this API.

URL address format

The URLs for the REST API endpoints use the tenant URL format, <host>/Relativity.Rest/API, followed by the path segment format — resource first, then node type (and node key for fileshare):

Considerations

• The groupId must be the instance-level group identifier. Workspace-level group IDs are not accepted.

• For mass updates across multiple fileshares, clients should:
  • Iterate through fileshare nodes sequentially.
  • Use the batch POST /role-assignments endpoint to assign/revoke multiple roles per node in a single request.
  • Respect rate limits and implement exponential backoff on 429 responses.

• Client must set API requests timeout to 30 seconds maximum.
• Clients should set appropriate timeouts and implement retry logic for transient failures (5xx responses).

Authentication requirements

Token requirements

• The token must be valid (not expired) and issued for the correct tenant.
• The user represented by the token must belong to groups that can view groups in the tenant (standard R1 group management permission).

Identifier guide

Node Key

The node key identifies a permissionable object (node) in the data hierarchy.

Nodes are addressed in the URL as path segments:

1
/access-control/public/v1/role-assignments/fileshare/B

For fileshare nodes the format is /role-assignments/{nodeType}/{nodeKey}. For tenant nodes the node key is omitted — the tenant is auto-resolved from the request context (tenant-based URL and bearer token).

Group ID (groupId)

The group ID identifies an R1 group id on instance level. It is a numeric string (integer).

The groupId used in this API is always the instance-level group identifier. Group IDs stored in workspace databases are not used in this public API. Use the instance-level group ID as seen in the Relativity instance administration.

Role Key (roleKey)

The role key identifies a named collection of permissions. All role keys follow the convention r1_{product}_{role_name} — the r1_ prefix is universal across all keys in this API.

Role key stability: Role keys follow the r1_{product}_{role_name} convention and are considered stable for the external API. If roles are added, existing role keys will not change. Deprecated roles will be communicated well in advance.

Typical use cases

The following are some typical use cases of programmatic interaction with the API by a Relativity application developer or administrator.

List current role assignments on a fileshare

Scenario: The operator wants to see which groups currently have roles assigned on a fileshare, for compliance or before making bulk changes.

1
2
GET /access-control/public/v1/role-assignments/fileshare/A
Authorization: Bearer {end-user-token}

1
2
3
4
[
  { "groupId": "1040719", "roleKey": "r1_staging_uploader" },
  { "groupId": "20", "roleKey": "r1_staging_viewer" }
]

The response returns only what the authenticated user is permitted to see:

• Roles: The user must hold the <domain>_secure permission for each domain role.
• Groups: Results are filtered to groups visible to the authenticated user based on the standard R1 view group permission.

Batch assign and revoke roles on a fileshare

Scenario: Onboard a new client domain. They need to assign the correct roles to several groups on fileshare "A" and revoke access for a group — all in a single request.

Both assign and revoke lists are optional , you may send only assigns, only revokes, or both in a single request. The operation is atomic: if any revoke targets a role that cannot be removed, the entire request fails and no changes are applied.

1
2
3
4
5
6
7
8
9
10
11
12
13
POST /access-control/public/v1/role-assignments/fileshare/A
Authorization: Bearer {end-user-token}
Content-Type: application/json

{
  "assign": [
    { "roleKey": "r1_staging_viewer", "groupId": "1050100" },
    { "roleKey": "r1_staging_uploader", "groupId": "1050101" }
  ],
  "revoke": [
    { "roleKey": "r1_staging_viewer", "groupId": "1040723" }
  ]
}

Response: 200 OK

1
2
3
{
  "message": "The requested resource does not exist or you do not have access to it."
}

All authorization failures return the same generic response regardless of whether the resource does not exist or the user lacks access. This prevents callers from inferring the existence of resources they cannot access.

List current role assignments on the tenant

Scenario: The operator wants to see which groups currently have tenant-level roles assigned (e.g., data_transfer), for compliance or before making changes. The tenant is automatically resolved from the authenticated user's token, no tenant identifier is needed in the URL.

1
2
GET /access-control/public/v1/role-assignments/instance
Authorization: Bearer {end-user-token}

1
2
3
[
  { "groupId": "1040719", "roleKey": "r1_staging_data-transfer" }
]

The same visibility rules apply as for fileshare nodes: the user must hold <domain>_secure on the tenant node, and group results are filtered by the user's view group permission.

Batch assign and revoke roles on the tenant

Scenario: User needs to grant the data_transfer capability to a group at the tenant level.

1
2
3
4
5
6
7
8
9
POST /access-control/public/v1/role-assignments/instance
Authorization: Bearer {end-user-token}
Content-Type: application/json

{
  "assign": [
    { "roleKey": "r1_staging_data-transfer", "groupId": "1050100" }
  ]
}

Response: 200 OK

1
2
3
4
5
6
7
8
9
POST /access-control/public/v1/role-assignments/instance
Authorization: Bearer {end-user-token}
Content-Type: application/json

{
  "revoke": [
    { "roleKey": "r1_staging_data-transfer", "groupId": "1050100" }
  ]
}

Response: 200 OK

The same atomicity and error handling rules apply as for fileshare operations.