The Role API allows you to programmatically manage custom roles and control role assignments for users within a Syncari subscription. All endpoints require a valid API token obtained via the OAuth client credentials flow.
List Roles
Returns all roles available in the current instance, including system roles and any custom roles that have been created.
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Example
Request Sample
curl --request GET \
--url https://api.syncari.com/api/v1/roles \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2023-09-01T00:00:00.000+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2023-09-01T00:00:00.000+00:00",
"name": "Org Admin",
"description": null,
"system": true,
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "INVITE_USER" },
{ "resourceId": "global", "privilegeId": "LIST_USER" }
]
},
{
"id": "64f1a2b3c4d5e6f7a8b9c0d2",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2024-01-10T08:00:00.000+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2024-01-10T08:00:00.000+00:00",
"name": "Pipeline Reviewer",
"description": "Read-only access with pipeline review privileges",
"system": false,
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "LIST_USER" },
{ "resourceId": "global", "privilegeId": "READ_STUDIO" }
]
}
]
} Get Role
Returns a single role by its ID.
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Path Parameters
Name | Type | Required |
id | string |
Example
Request Sample
curl --request GET \
--url https://api.syncari.com/api/v1/roles/64f1a2b3c4d5e6f7a8b9c0d2 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result":
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2023-09-01T00:00:00.000+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2023-09-01T00:00:00.000+00:00",
"name": "Org Admin",
"description": null,
"system": true,
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "INVITE_USER" },
{ "resourceId": "global", "privilegeId": "LIST_USER" }
]
}
} Create Role
Creates a new custom role in the current instance. System roles (Org Admin, Sync Manager, Viewer, etc.) cannot be created via this API - they are provisioned automatically. Required permission: ADD_ROLE (Org Admin or above)
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Body
Name | Type | Required |
name Unique name for the role | string | |
description Human-readable description of the role's purpose
| string | |
active Whether the role is active. Default: true
| boolean | |
privileges List of privilege objects to assign to the role. Each object has resourceId and privilegeId fields
| array | |
userIds List of user IDs to assign this role to upon creation
| array |
Example
Request Sample
curl --request POST \
--url https://api.syncari.com/api/v1/roles \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99'
--data '{
"name": "Pipeline Reviewer",
"description": "Read-only access with pipeline review privileges",
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "LIST_USER" },
{ "resourceId": "global", "privilegeId": "READ_STUDIO" },
{ "resourceId": "global", "privilegeId": "READ_DATA_STUDIO" }
],
"userIds": ["62789f7daa9138df5bc688f5"]
}' Response Sample
Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result":
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2023-09-01T00:00:00.000+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2023-09-01T00:00:00.000+00:00",
"name": "Org Admin",
"description": null,
"system": true,
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "INVITE_USER" },
{ "resourceId": "global", "privilegeId": "LIST_USER" }
]
}
} Update Role
Updates an existing custom role. System roles cannot be updated via this API.
Required permission: EDIT_ROLE (Org Admin or above)
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Path Parameters
Name | Type | Required |
id | string |
Body
Name | Type | Required |
name Role name (must be unique) | string | |
active Whether the role is active | boolean | |
privileges Full replacement set of privileges. Replaces all existing privileges | array | |
userIds Full replacement set of user IDs assigned to this role | array |
Example
Request Sample
curl --request PUT \
--url https://api.syncari.com/api/v1/roles/64f1a2b3c4d5e6f7a8b9c0d2 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99'
--data '{
"name": "Pipeline Reviewer",
"description": "Read-only access with pipeline review privileges",
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "LIST_USER" },
{ "resourceId": "global", "privilegeId": "READ_STUDIO" },
{ "resourceId": "global", "privilegeId": "READ_DATA_STUDIO" },
{ "resourceId": "global", "privilegeId": "READ_BUSINESS_STUDIO" }
],
"userIds": ["62789f7daa9138df5bc688f5"]
}' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result":
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2023-09-01T00:00:00.000+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2023-09-01T00:00:00.000+00:00",
"name": "Org Admin",
"description": null,
"system": true,
"active": true,
"privileges": [
{ "resourceId": "global", "privilegeId": "INVITE_USER" },
{ "resourceId": "global", "privilegeId": "LIST_USER" },
{ "resourceId": "global", "privilegeId": "READ_DATA_STUDIO" },
{ "resourceId": "global", "privilegeId": "READ_BUSINESS_STUDIO" }
]
}
} Delete Role
Permanently deletes a custom role. Any users assigned to this role will have the role removed automatically. System roles cannot be deleted.
Required permission: DELETE_ROLE (Org Admin or above) Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Path Parameters
Name | Type | Required |
id | string |
Example
Request Sample
curl --request DELETE \
--url https://api.syncari.com/api/v1/roles/64f1a2b3c4d5e6f7a8b9c0d2 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result": "Role deleted"
} Assign Roles to User
Sets the roles for a user in the current instance. This replaces all existing role assignments for that user in this instance.
Required permission: ADD_ROLE_TO_USR (Org Admin or above)
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Path Parameters
Name | Type | Required |
userId | string |
Body
Name | Type | Required |
roleNames List of role names to assign. Must match existing role names exactly | string |
Example
Request Sample
curl --request PUT \
--url https://api.syncari.com/api/v1/users/62789f7daa9138df5bc688f5/roles \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99'
--data '{
"roleNames": ["Viewer", "Pipeline Reviewer"]
}' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result": {
"id": "62789f7daa9138df5bc688f5",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2022-05-09T04:58:37.259+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2024-01-15T10:27:00.000+00:00",
"email": "analyst@example.com",
"status": "ACTIVE",
"firstName": "Alex",
"lastName": "Analyst",
"userRoles": {
"YUBV99": ["Viewer", "Pipeline Reviewer"]
},
"apiUser": false
}
}
Remove Role from User
Removes a single role from a user in the current instance.
Required permission: REMOVE_ROLE_FROM_USR (Org Admin or above)
Request Headers
Name | Type | Required |
syncariId Id of the instance the api is to be run against | string | |
clientRequestId Client side request id to be used for idempotency in the future
| string |
Path Parameters
Name | Type | Required |
userId | string | |
| roleId | string |
Example
Request Sample
curl --request DELETE \
--url https://api.syncari.com/api/v1/users/62789f7daa9138df5bc688f5/roles/64f1a2b3c4d5e6f7a8b9c0d2 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'clientRequestId: my-request-001' \
--header 'syncariId: YUBV99' Response Sample
{
"success": true,
"requestId": "1092384756",
"timestamp": "2024-01-15T10:22:00.000000Z",
"result": {
"id": "62789f7daa9138df5bc688f5",
"createdBy": "61e2a0f134a0f06932046bab",
"createdAt": "2022-05-09T04:58:37.259+00:00",
"updatedBy": "61e2a0f134a0f06932046bab",
"updatedAt": "2024-01-15T10:28:00.000+00:00",
"email": "analyst@example.com",
"status": "ACTIVE",
"firstName": "Alex",
"lastName": "Analyst",
"userRoles": {
"YUBV99": ["Viewer"]
},
"apiUser": false
}
}