User Endpoints
User Endpoints and Parameters
To find out more about the objects relations, go to the Object Relations section.
For more information about users, visit the User and Group Management help page.
Create a New User
To create a new user record, use the POST {baseURL}/v3/users endpoint.
Note
Only Curators can use this API endpoint.
This endpoint can’t be used for Windows Authentication configured Server instances.
Parameters
userContract (body): To create a new user, the userContract parameter is required. Specify the following parameters:
firstName (string): Required. Enter a user’s first name.
lastName (string): Required. Enter a user’s last name.
email (string): Required. Enter a user’s email address.
role (string): Optional. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated (the default role evaluated at runtime). For more information about roles and permissions, visit the User Roles and Permissions page. When no role is selected, the default is the Evaluated role.
defaultWorkerTag (string): Optional. Specify the worker tag defined in the workers to help assign jobs to certain worker nodes. When not specified, the default is "". For more information, visit the Worker help page.
canScheduleJobs (boolean): Optional. Specify whether the user can schedule jobs. When not specified, the default is false. For more information, visit the Jobs help page.
canPrioritizeJobs (boolean): Optional. Specify whether a user can prioritize jobs. When not specified, the default is false. For more information, visit the Jobs help page.
canAssignJobs (boolean): Optional. Specify whether a user can assign jobs. When not specified, the default is false. For more information, visit the Jobs help page.
canCreateCollections (boolean): Optional. Specify whether a user can create new collections. When not specified, the default is false. For more information, visit the Collections help page.
isApiEnabled (boolean): Optional. Specify whether the API is enabled for a user. When not specified, the default is false.
defaultCredentialId (string): Optional. This parameter refers to the unique ID of a workflow, assigned to the user as default. When not specified, the default is "".
isActive (boolean): Optional. Select whether a user is active or deactivated. When not specified, the default is true.
timeZone (string): Optional. Enter the time zone, for example, Europe/Kiev. When not specified, the default is "".
canCreateAndUpdateDcm (boolean): If set to ‘true’, it allows the user to create or update DCM assets (data sources, credentials, and external vaults). Without this permission, users cannot create, edit, and synchronize DCM assets from Designer.
canShareForExecutionDcm (boolean): If set to ‘true’, it allows the user to share DCM connection credentials to run on Server only.
canShareForCollaborationDcm (boolean): If set to ‘true’, it allows the user to share DCM connection credentials for collaboration.
canManageGenericVaultsDcm (boolean): If set to ‘true’, it allows the user to manage DCM generic vaults.
Request Example: cURL
curl --location --request POST 'http://localhost/webapi/v3/users' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'firstName=John' \ --data-urlencode 'lastName=Doe' \ --data-urlencode 'email=John.Doe@emailexample.com'
Deactivate a User
To deactivate a user in the system, use the POST {baseURL}/v3/users/{userId}/deactivate endpoint.
Note
Only Curators can use this API endpoint.
As a response, you get an array of user group IDs that the deactivated user is removed from.
Parameters
userId (string): Required. Enter a user ID to deactivate this user.
Request Example: cURL
curl --location --request POST 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b/deactivate' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Send a Password Reset Email to a User
To send a password reset email to an existing user, use the POST {baseURL}/v3/users/{userId}/passwordReset endpoint.
Note
Only Curators can use this API endpoint.
This endpoint can't be used for Windows Authentication and SAML Authentication configured Server instances.
Parameters
userId (string): Required. Enter a user ID to send a reset email to the user.
Request Example: cURL
curl --location --request POST 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b/passwordReset' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Retrieve all User Records
To retrieve all accessible user records, use the GET {baseURL}/v3/users endpoint. Use various parameters as a filter.
Note
Only Curators can use this API endpoint.
If the searchContract.Verbose is set to false, then a reduced view object will be returned.
Parameters
view (string): Optional. Can be left without a value. You can choose from the following values: ‘Default’ and ‘Full’. If this parameter is set to 'Default’, then a reduced view object will be returned. When not specified, the ‘Default’ value is used.
active (boolean): Optional. Select whether a user is active or deactivated.
email (string): Optional. Enter user’s email address.
role (string): Optional. Select the user role to narrow the search. Select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. The default (Evaluated) role is evaluated at runtime. For more information about roles and permissions, visit the User Roles and Permissions page.
firstName (string): Optional. Enter user’s first name.
lastName (string): Optional. Enter user’s last name.
createdAfter (date-time): Optional. Enter the date and time after which the user was created. Enter the date and time in ISO8601 format.
createdBefore (date-time): Optional. Enter the date and time before which the user was created. Enter the date and time in ISO8601 format.
Request Example: cURL
curl --location --request GET 'http://localhost/webapi/v3/users?view=Full&active=true&lastName=Doe' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Retrieve Details about a Specific User
To retrieve details about an existing user, use the GET {baseURL}/v3/users/{userId} endpoint.
Note
Only Curators can use this API endpoint.
Parameters
userId (string): Required. Enter a user ID to retrieve details about this user.
Request Example: cURL
curl --location --request GET 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Retrieve All Assets a User Owns
To get a full list of accessible assets that an existing user owns, use the GET {baseURL}/v3/users/{userId}/assets endpoint.
Note
Only Curators can use this API endpoint.
Parameters
userId (string): Required. Enter a user ID to retrieve the list of assets for this user.
assetType (string): Optional. Select the asset types you want to return. Default is set to 'All'.
Request Example: cURL
curl --location --request GET 'http://localhost/webapi/v3/users/61d564361d6d5da7ad461a32/assets?assetType=Workflows' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Transfer All Assets a User Owns to Another
To transfer all assets (workflows, schedules, and collections) owned by one user to another, use the PUT {baseURL}/v3/users/{userId}/assetTransfer endpoint.
Note
Only Curators can use this API endpoint.
If any of the workflows require DCM connections, Server connections, or specific run as credentials to run, these items need to be updated before the workflow can run.
If users are not in the same studio and when a workflow is transferred to the new studio, all other users in the new owner's studio will also receive access to the workflow, and all users from the old studio will lose access.
Workflows can only be transferred to a user with the Artisan or Curator role.
If transferring schedules, the new owner must have access to the scheduled workflow, otherwise you won’t be able to transfer that workflow to the new owner.
If transferring schedules, the new owner must have permission to schedule workflows.
If the user is deleted, it returns a list of schedule Ids that will be broken or disabled after transfer.
Parameters
userId (string): Required. Id of the user to transfer assets from.
contract (body):
ownerId (string): Specify the Id of the user to transfer assets to (new owner).
transferWorkflows (Boolean): Specify whether the workflows should be transferred to the new owner.
transferSchedules (Boolean): Specify whether the schedules should be transferred to the new owner.
transferCollections (Boolean): Specify whether the collections should be transferred to the new owner.
Request Example: cURL
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ "ownerId": "63d17f6cb049da66d0afd4e2", \ "transferWorkflows": true, \ "transferSchedules": true, \ "transferCollections": true \ }' 'http://localhost/webapi/v3/users/613a523df9199abfc446d19d/assetTransfer'
Update an Existing User
To update details of an existing user, use the PUT {baseURL}/v3/users/{userId} endpoint.
Note
Only Curators can use this API endpoint.
The ID of the updateContract will be overwritten by the ID value in the URL.
Parameters
userId (string): Required. Enter a user ID to get this user updated.
updateContract (body): Required. To update a user, the updateContract parameter is required. Specify the following:
id (string): Optional. Enter a user ID to get it updated.
firstName (string): Required. Enter a user’s first name.
lastName (string): Required. Enter a user’s last name.
email (string): Required. Enter a user’s email address.
role (string): Required. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. For more information about roles and permissions, visit the User Roles and Permissions page.
defaultWorkerTag (string): Required. Specify the worker tag defined in the workers to help assign jobs to certain worker nodes. For more information about workers, visit the Worker help page.
canScheduleJobs (boolean): Required. Specify whether a user can schedule jobs. For more information, visit the Jobs help page.
canPrioritizeJobs (boolean): Required. Specify whether a user can prioritize jobs. For more information, visit the Jobs help page.
canAssignJobs (boolean): Required. Specify whether a user can assign jobs. For more information, visit the Jobs help page.
canCreateCollections (boolean): Optional. Specify whether a user can create collections. When not specified, the value stays the same as before. For more information, visit the Collections help page.
isApiEnabled (boolean): Required. Specify whether the API is enabled for a user.
defaultCredentialId (string): Required. This parameter refers to the unique ID of a workflow, assigned to the user as default.
isAccountLocked (boolean): Required. Select whether to lock this user account.
isActive (boolean): Required. Select whether a user is active or deactivated.
isValidated (boolean): Required. Specify whether a user’s email address is validated.
timeZone (string): Required. Enter the time zone, e.g., Europe/Kiev, etc.
language (string): Required. Supported language values are "de-de", "en-us", "es-es", "fr-fr", "it-it", "ja-jp", "pt-br", "zh-cn".
canCreateAndUpdateDcm (boolean): If set to ‘true’, it allows the user to create or update DCM assets (data sources, credentials, and external vaults). Without this permission, users cannot create, edit, and synchronize DCM assets from Designer.
canShareForExecutionDcm (boolean): If set to ‘true’, it allows the user to share DCM connection credentials to run on Server only.
canShareForCollaborationDcm (boolean): If set to ‘true’, it allows the user to share DCM connection credentials for collaboration.
canManageGenericVaultsDcm (boolean): If set to ‘true’, it allows the user to manage DCM generic vaults.
Request Example: cURL
curl --location --request PUT 'http://localhost/webapi/v3/users/61d564361d6d5da7ad461a32' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'firstName=Doe' \ --data-urlencode 'lastName=Jane' \ --data-urlencode 'email=jdoe@alteryx.com' \ --data-urlencode 'role=Artisan' \ --data-urlencode 'defaultWorkerTag=worker' \ --data-urlencode 'canScheduleJobs=true' \ --data-urlencode 'canPrioritizeJobs=true' \ --data-urlencode 'canAssignJobs=true' \ --data-urlencode 'canCreateCollections=true' \ --data-urlencode 'isApiEnabled=true' \ --data-urlencode 'defaultCredentialId=jdoe' \ --data-urlencode 'isAccountLocked=true' \ --data-urlencode 'isActive=true' \ --data-urlencode 'isValidated=true' \ --data-urlencode 'timeZone=Europe/Prague' \ --data-urlencode 'language=en-us' \ --data-urlencode 'id=61d564361d6d5da7ad461a32'
Delete a User
To delete an existing user from the system, use the DELETE {baseURL}/v3/users/{userId} endpoint.
Note
Only Curators can use this API endpoint.
If the user you want to delete has any assets (workflows, schedules, collections) or user groups assigned, then this user can’t be deleted.
Parameters
userId (string): Required. Enter the user ID you want to delete.
Request Example: cURL
curl --location --request DELETE 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Objects Relations
If you are creating a user, you can use created objects as follows:
Object created: "id" (for example, "id": "619158e57e607d0011ac3009")
You can use it as:
userId if you are adding users to a user group.
userId if you are removing user from a user group.
userId if you are searching for a specific user.
ownerId if you are uploading a workflow.
userId if you are adding a user from a collection.
userId if you are removing a user from a collection.
userId if you are updating user permissions for a collection.
ownerId if you are searching for a schedule.
userId if you want to share a credential with a user.
userId if you want to remove a user from a credential.
userId if you want to add a user to an existing data connection.
userId if you want to remove a user from an existing data connection.
Postman Request Examples
GET /v3/users
GET /v3/users/{id}/assets
To know more about Postman requests, visit the How to Use Postman help page.