Sharing

Manage how your users and groups can access your Talend Cloud entities.

Contact: Talend

Endpoints

https://api.eu.cloud.talend.com
URL for the AWS Europe region
https://api.ap.cloud.talend.com
URL for the AWS Asia Pacific region
https://api.us.cloud.talend.com
URL for the AWS United States East region
https://api.au.cloud.talend.com
URL for the AWS Australia region
https://api.us-west.cloud.talend.com
URL for the Azure United States West region

Global security

These security schemes apply to the entire API

Public

Security scheme

This scheme can be referenced across the API

Public

This Bearer authentication can be set in the Authorization header of your requests.

Authentication tokens and Personal Access Tokens are supported.

Personal Access Tokens can be generated in the Profile Preferences page of the Talend Cloud Portal.

Bearer authentication
Name	Description
Format	Bearer <token>

Get a sharingset for an entity

GET /sharing/sharingset/{entityType}/{entityId}

Use this method to retrieve a sharingset. A sharingset represents the full list of users and groups who have access to the specified entity.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation
entityId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473

Query parameters
Name	Description	Type	Attributes and examples
foreignEntityType		string Optional	Example api_test
limit	Limits the number of elements displayed in the sharingset.	integer Optional	FormatINT32 Example 100
offset		integer Optional	FormatINT32 Example 1000
includeDeletedSharings	True or false	boolean Optional
foreignEntityId		string Optional	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

SharingSetResponse

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Patch a sharingset for an entity

PATCH /sharing/sharingset/{entityType}/{entityId}

A sharingset represents the full list of users and groups who have access to the specified entity. Use this method to patch the sharingset and define who can access a given entity, and with which access level (viewer, editor, owner). Unlike the PUT operation that replaces the whole sharingset, the PATCH operation allows you to apply specific changes to the sharingset. A missing level stands for a removal command of a user or group sharing.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation
entityId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Body

PatchSharingSetRequest

Response

200Status 200

Status 200

Body

SharingSetKey

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Update a sharingset for an entity

PUT /sharing/sharingset/{entityType}/{entityId}

A sharingset represents the full list of users and groups who have access to the specified entity. Use this method to update the sharingset by defining who can access a given entity, and with which access level (viewer, editor, owner). This PUT operation allows you to replace the whole sharingset with the new information.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation
entityId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Body

PutSharingSetRequest

Response

200Status 200

Status 200

Body

SharingSetKey

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Get the access levels of an entity

GET /sharing/sharings/levels/{entityType}

An access level defines to what extent the user or the group will be able to interact with the entity. In Talend Cloud, the available levels are Viewer, Editor, and Owner. Depending on the level, a user will have read-only or write permissions for example. Use this method to retrieve the available access levels of the specified entity type.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

array of LevelResponse

Datatype details
Type	Description	Attributes and examples
array
LevelResponse

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

GET /sharing/sharings/eligibles/{entityType}

Use this method to retrieve the list of users and groups with whom a specific entity type can be shared. The list of available users and groups changes depending on which permissions they are assigned in Talend Management Console.

Use cases

Creating a crawler from a JDBC connection

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

Eligibles

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Get the entities that the current user has access to

GET /sharing/sharings/{entityType}

Use this method to retrieve the list of all entities of a given type that the current user has access to. This list of access also includes the access level and the UUID of the entity.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation

Query parameters
Name	Description	Type	Attributes and examples
includeMetadata		boolean Optional

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

array of SharingResponse

Datatype details
Type	Description	Attributes and examples
array
SharingResponse

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Get users/groups' access information to an entity

GET /sharing/sharings/{entityType}/{entityId}

Use this method to get the list of computed accesses by users or groups to a given entity.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation
entityId		string Required

Query parameters
Name	Description	Type	Attributes and examples
includeMetadata		boolean Optional

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

SharingResponse

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Patch a sharingset

PATCH /sharing/sharingset

A sharingset represents a list of users and groups. Use this method to patch a list of sharingsets. The PATCH operation allows you to apply specific changes to the sharingset without replacing it entirely.

Request

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Body

BulkSharingSetRequest

Response

200Status 200

Status 200

Body

SharingSetKey

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

Get the list of permissions for an entity

GET /sharing/sharings/{entityType}/{entityId}/entitlements

Use this method to rerieve a list of available permissions for a given entity.

Request

Path variables
Name	Description	Type	Attributes and examples
entityType		string Required	Example preparation
entityId		string Required

Headers
Name	Description	Type	Attributes and examples
X-CLIENT-VERSION		string Optional

Response

200Status 200

Status 200

Body

EntitlementsResponse

400Status 400

Bad request

Body

ErrorMessageBody

401Status 401

Not authenticated

Body

ErrorMessageBody

403Status 403

Not authorized

Body

ErrorMessageBody

404Status 404

Not found

Body

ErrorMessageBody

500Status 500

Internal Server Error

Body

ErrorMessageBody

502Status 502

Bad gateway

Body

ErrorMessageBody

503Status 503

Service unavailable

Body

ErrorMessageBody

This object is returned in case of an error during an API call.

Object

Name	Type	Attributes and examples
timestamp	integer Required	FormatINT64 Example 1622618273418
status	integer Required	FormatINT32 Example 400
error	string Required	Example Bad Request
exception	string Optional
message	string Optional	Example The request is invalid
path	string Required	Example /sharing/sharings/levels/dataset

Name	Type	Attributes and examples
code	string Required	Example WRITER
label	string Required	Example Editor
order	integer Required	FormatINT32 Example 2

Description of a list of users and groups of users who are eligibles for the sharing of an entit.

Object

users

array of User Optional

Datatype details
Type	Description	Attributes and examples
array
User

groups

array of Group Optional

Datatype details
Type	Description	Attributes and examples
array
Group

Basic description of an user, with its id, first name and last name.

Object

Name	Description	Type	Attributes and examples
userId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
firstName		string Required	Example John
lastName		string Required	Example Frusciante

Desription of group of users, with the group id and its name.

Object

Name	Description	Type	Attributes and examples
groupId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
groupName		string Required	Example IT department

Object

entityType

string Required

Example

dataset

entityId

UUID

string Required

Example

15de7eb2-6447-49a8-a404-a53ecd1f3473

userId

UUID

string Required

Example

15de7eb2-6447-49a8-a404-a53ecd1f3473

levelCode

string Required

Example

entitlements

array of string Optional

Datatype details
Type	Description	Attributes and examples
array
string		Example DATASET_READ

userOwners

array of UserSharingResponse Optional

Datatype details
Type	Description	Attributes and examples
array
UserSharingResponse

groupOwners

array of GroupSharingResponse Optional

Datatype details
Type	Description	Attributes and examples
array
GroupSharingResponse

sharingSetCount

integer Optional

FormatINT32

Example

isSharedWithOthers

boolean Optional

Object

Name	Description	Type	Attributes and examples
userId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelResponse Required
firstName		string Optional	Example John
lastName		string Optional	Example Frusciante
foreignEntity		ForeignEntity Required
deletedAt		datetime Optional	FormatRFC3339

Name	Description	Type	Attributes and examples
entityId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
entityType		string Required	Example dataset

Object

Name	Description	Type	Attributes and examples
groupId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelResponse Required
groupName		string Optional	Example IT department
foreignEntity		ForeignEntity Required
deletedAt		datetime Optional	FormatRFC3339

Object

entityId

UUID

string Required

Example

15de7eb2-6447-49a8-a404-a53ecd1f3473

entitlements

array of string Optional

Datatype details
Type	Description	Attributes and examples
array
string		Example DATASET_READ

Object

users

array of UserSharingResponse Optional

Datatype details
Type	Description	Attributes and examples
array
UserSharingResponse

groups

array of GroupSharingResponse Optional

Datatype details
Type	Description	Attributes and examples
array
GroupSharingResponse

Name	Description	Type	Attributes and examples
code		string Required	Example WRITER

Name	Description	Type	Attributes and examples
entityType		string Required	Example dataset
entityId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473

Object

users

array of PutUserSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PutUserSharingRequest

groups

array of PutGroupSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PutGroupSharingRequest

Object

Name	Description	Type	Attributes and examples
userId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelRequest Required
firstName		string Optional	Example John
lastName		string Optional	Example Frusciante
foreignEntity		ForeignEntity Optional

Object

Name	Description	Type	Attributes and examples
groupId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelRequest Required
groupName		string Optional	Example IT department
foreignEntity		ForeignEntity Optional

Object

users

array of PatchUserSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PatchUserSharingRequest

groups

array of PatchGroupSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PatchGroupSharingRequest

Object

Name	Description	Type	Attributes and examples
userId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelRequest Optional
firstName		string Optional	Example John
lastName		string Optional	Example Frusciante
foreignEntity		ForeignEntity Optional

Object

Name	Description	Type	Attributes and examples
groupId	UUID	string Required	Example 15de7eb2-6447-49a8-a404-a53ecd1f3473
level		LevelRequest Optional
groupName		string Optional	Example IT department
foreignEntity		ForeignEntity Optional

Object

bulk

array of Object Required

array

Object

entityId

UUID

string Required

Example

15de7eb2-6447-49a8-a404-a53ecd1f3473

entityType

string Required

Example

dataset

users

array of PatchUserSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PatchUserSharingRequest

groups

array of PatchGroupSharingRequest Optional

Datatype details
Type	Description	Attributes and examples
array
PatchGroupSharingRequest

↑

Sharing

Endpoints

Global security

Security scheme

Get a sharingset for an entity

Request

Response

Patch a sharingset for an entity

Request

Response

Update a sharingset for an entity

Request

Response

Get the access levels of an entity

Request

Response

Get eligible users/groups for sharing

Use cases

Request

Response

Get the entities that the current user has access to

Request

Response

Get users/groups' access information to an entity

Request

Response

Patch a sharingset

Request

Response

Get the list of permissions for an entity

Request

Response

ErrorMessageBody

LevelResponse

Eligibles

User

Group

SharingResponse

UserSharingResponse

ForeignEntity

GroupSharingResponse

EntitlementsResponse

SharingSetResponse

LevelRequest

SharingSetKey

PutSharingSetRequest

PutUserSharingRequest

PutGroupSharingRequest

PatchSharingSetRequest

PatchUserSharingRequest

PatchGroupSharingRequest

BulkSharingSetRequest