Public API v1 → 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 v1, refer to References → Public API v1.
You must use the HTTPS
scheme to be able to successfully run the API endpoints.
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/v1/users/transferOwnership
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 v1 → Create Token Endpoint.
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 | 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."} |
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. | {"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'][]"} |