Public API v2 → Transfer Ownership Endpoint

About the /users/transferOwnership endpoint

The /users/transferOwnership endpoint transfers the ownership of all entities that a specific user owns to another active user. It can also transfer all the share permissions assigned to this user to the other user.

Only the Super User or a user manager can use the /users/transferOwnership endpoint.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints. Additionally, you must specify the tenant name (case-sensitive) in the endpoint request URL starting with the 2023.7.0 release.

Important

If the endpoint fails to transfer the ownership of any of the entities, the whole operation fails. The system tracks ownership transfers for audit purposes.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenantName}/users/transferOwnership

Request URL Parameter

Field name	Description	Type	Required
tenantName	The tenant name (case-sensitive)	String	Required starting with 2023.7.0

HTTP method

PATCH

Request headers

{
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access_token}"
}

You must use a valid access token of a Super User or a user with the Super Role or User Manager role.

For information about how to create an access token, refer to Public API v2 → Create an API access token.

Request body

{
  "ownerEmail": "string",
  "newOwnerEmail": "string",
  "transferSharingPermission": boolean
}

Request body parameters

The following table describes the request body parameters in the /users/transferOwnership endpoint.

Parameter	Type	Description	Required?	Notes
ownerEmail	String	The email address of the owner user as defined in the system	Required
newOwnerEmail	String	The email address of the user you want to transfer the entity ownership to	Required	● The new owner must be assigned roles similar to or higher than those assigned to the original owner. ● The new owner must be an active user. Therefore, you cannot transfer the ownership to an inactive user; an invitee who has not accepted the invitation, for example.
transferSharingPermission	Boolean	Specify if the share permissions assigned to the original user on other entities should be transferred as well or not	Optional	Valid values are ● True ● False (default)

Request body example

{
  "ownerEmail": "originalUser@myComp.net",
  "newOwnerEmail": "newUser@myComp.net",
  "transferSharingPermission": true
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
200	OK The endpoint transferred all entities successfully.	`{"message": "string"}` Example: `{"message": "Objects transferred successfully"}`
400	Bad Request The endpoint couldn’t transfer the ownership of all entities because of one or more of the following: ● The email address does not match an existing user. ● The new owner is not an active user. ● The new user doesn’t have the same roles.	`{"message": "string"}` Example: `{"message": "INC_02010404: The user with Email [newUser@myComp.net] cannot be found."}`
401	Unauthorized The tenant name doesn’t match the tenant in the access token.	`{"message": "string"}`
403	Forbidden The endpoint couldn’t transfer the ownership of all entities due to authentication errors, such as an invalid or expired access token.	`{"message": "string"}` Example: `{"message": "INC_09030101: Invalid access token or access token may have expired."}`
404	Not Found ● The endpoint couldn’t find any entity that the original user owns. ● The tenant doesn't exist or is disabled.	`{"message": "string"}` Example: `{"message": "INC_02010209: The user does not have any objects."}`
500	Internal Server Error The endpoint couldn’t transfer the ownership of all entities due to a server error. For example, the new user has one or more entities that share the same name as the entities that the original user owns.	`{"message": "string"}` Example: `{"message": "INC_02010200: Internal SQL exception [Duplicate entry '202-155-New Dashboard' for key 'NAME_PARENT_DASHBOARD'][]"}`

Content