openapi: 3.2.0
info:
title: Visier Administration Users V1 API
description: Visier APIs for managing your tenant or tenants in Visier. You can programmatically manage user accounts in Visier, the profiles and permissions assigned to users, and to make changes in projects and publish projects to production. Administrating tenant users can use administration APIs to manage their analytic tenants and consolidated analytics tenants.<br>**Note:** If you submit API requests for changes that cause a project to publish to production (such as assigning permissions to users or updating permissions), each request is individually published to production, resulting in hundreds or thousands of production versions. We recommend that you use the `ProjectID` request header to make changes in a project, if `ProjectID` is available for the API endpoint.
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 22222222.99201.3040
security:
- ApiKeyAuth: []
BearerAuth: []
- ApiKeyAuth: []
CookieAuth: []
- ApiKeyAuth: []
OAuth2Auth: []
tags:
- name: UsersV1
x-displayName: Users V1
description: 'Manage users within an organization, such as assigning permissions to users and retrieving user permission assignments and application logs.
<br>**Tip:** Visier recommends that administrating tenant users focus primarily on managing users at the administrating tenant level. These users likely belong directly to your organization, such as customer support, customer value managers, account executives, and customer success. These users work with clients to manage their day-to-day solution needs'
paths:
/v1/admin/permissions/users:
put:
tags:
- UsersV1
summary: Assign permissions to users
description: "This API allows you to assign a permission to specific users. Administrating tenant users can assign permissions\n to users in the administrating tenant and in the analytic tenants those users belong to.\n\n To assign permissions to users in a project for the administrating tenant, provide a project UUID in the `ProjectID` request header.\n Administrating tenants can assign permissions to users in analytic tenants by providing a tenant code and project ID in the request body."
operationId: UsersV1_AssignPermissions
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
- name: SessionBasedPermissions
in: header
description: If `true`, the API call assigns user permissions that are only valid for the specified `SessionRepoId` without creating a new production version. When a user signs in to your application with the `SessionRepoId`, their session-based permissions are valid until the user session ends. Cannot be `true` if `NonVersioned` is `true`. Default is `false`.<br>**Note:** <em>This header is in **limited availability**. If you are interested in using it, please contact your Customer Success Manager (CSM).</em>
schema:
type: boolean
- name: SessionRepoId
in: header
description: Optionally, specify a session repository ID to overwrite the user's permissions that are associated with the `SessionRepoId`. Only valid with `SessionBasedPermissions`. If omitted and `SessionBasedPermissions` is `true`, the API creates a new `SessionRepoId`.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.AssignRevokePermissionsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.AssignRevokePermissionsResponseDTO'
delete:
tags:
- UsersV1
summary: Remove permissions from users
description: "This API allows you to remove a permission from specific users. Administrating tenant users can remove permissions\n from users in the administrating tenant and in the analytic tenants those users belong to.\n\n To remove permission from users in a project for the administrating tenant, provide a project UUID in the `ProjectID` request header.\n Administrating tenants can remove permissions from users in analytic tenants by providing a tenant code and project ID in the request body."
operationId: UsersV1_RemovePermissions
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.AssignRevokePermissionsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.AssignRevokePermissionsResponseDTO'
/v1/admin/permissions/{permissionId}/users:
get:
tags:
- UsersV1
summary: Retrieve users that are assigned a specific permission
description: "This API allows you to retrieve all the users that are assigned a specified permission. You must know the ID\n of the permission you want to retrieve users for.\n\n To specify the project in which to retrieve users assigned to a specific permission for the login tenant, provide\n a project UUID in the `ProjectID` request header. If omitted, the request retrieves users assigned to a specific permission from production."
operationId: UsersV1_GetPermissionAssignedUsers
parameters:
- name: permissionId
in: path
description: The unique identifier of the permission you want to retrieve users for.
required: true
schema:
type: string
- name: includeUserGroups
in: query
description: "If `true`, the response returns a list of all users that are assigned the permission, including users that are\n assigned the permission through a user group.\n If `false`, the response returns a list of the users that are directly assigned the permission."
schema:
type: boolean
- name: tenantFilter
in: query
description: Specify the tenant to retrieve the list of users from.
schema:
type: string
- name: limit
in: query
description: The number of results to return. The maximum number of tenants to retrieve is 100.
schema:
type: integer
format: int32
- name: start
in: query
description: The index to start retrieving results from, also known as offset. The index begins at 0.
schema:
type: integer
format: int32
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.PermissionAssignedUsersDTO'
/v1/admin/user-groups:
get:
tags:
- UsersV1
summary: Retrieve a list of all user groups
description: "This API allows you to retrieve the full list of user groups in a tenant.\n\n To specify the project in which to retrieve user groups for a tenant, provide a project UUID in the `ProjectID` request header. If omitted, the request retrieves user information from production."
operationId: UsersV1_GetAllUserGroups
parameters:
- name: tenantCode
in: query
description: Specify the tenant to retrieve the list of user groups from.
schema:
type: string
- name: limit
in: query
description: The number of results to return. The maximum number of users to retrieve is 1000.
schema:
type: integer
format: uint32
- name: start
in: query
description: The index to start retrieving results from, also known as offset.
schema:
type: integer
format: uint32
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.UserGroupsGetAPIResponseDTO'
/v1/admin/user-groups/permissions:
put:
tags:
- UsersV1
summary: Assign permissions to user groups
description: "This API allows you to assign a permission to specific user groups. This assigns the permission to all users in the user group.\n\n To assign permissions to user groups in a project, provide a project UUID in the `ProjectID` request header."
operationId: UsersV1_AssignPermissionsToUserGroups
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/admin.PermissionsToUserGroupsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.PermissionsToUserGroupForTenantDTO'
delete:
tags:
- UsersV1
summary: Remove permissions from user groups
description: "This API allows you to remove a permission from specific user groups.\n\n To remove permissions from user groups in a project, provide a project UUID in the `ProjectID` request header."
operationId: UsersV1_RevokePermissionsFromUserGroups
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/admin.PermissionsToUserGroupsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.PermissionsToUserGroupForTenantDTO'
/v1/admin/user-groups/users:
put:
tags:
- UsersV1
summary: Assign users to user groups
description: "This API allows you to assign users to specific user groups.\n\n To assign users to user groups in a project for the administrating tenant, provide a project UUID in the `ProjectID` request header.\n Administrating tenants can assign users to user groups in multiple analytic tenants by providing a tenant code and project ID in the request body.\n\n We recommend that administrating tenants set the analytic tenant in which to execute the API call using the `TargetTenantID` request header."
operationId: UsersV1_AddUsersToUserGroup
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
- name: Prefer
in: header
description: 'When `NonVersioned: true`, use `Prefer` to optionally specify if API calls should be subject to locking. Locking prevents incremental changes in multiple API calls from overwriting each other. The `Prefer` header works alongside a tenant feature flag. When enabled, the default is `nvLock=global`. When disabled, the default is not to lock API calls. Contact Visier Technical Support to enable the tenant feature flag.
Valid values for the `Prefer` header:
* `nvLock=global`: Run API calls sequentially. Sequential API calls prevent calls from unintentionally overwriting each other.
* `nvLock=artifact`: Allow API calls in parallel. Parallel API calls only work if the calls do not conflict with each other. If a change wasn''t applied, the request fails and returns the HTTP 409 conflict error. Run the request again until successful.
* `nvLock=none`: Disable the global lock if the tenant feature flag is enabled.'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/admin.UsersToUserGroupsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.SecurityAssignmentResponseDTO'
delete:
tags:
- UsersV1
summary: Remove users from user groups
description: "This API allows you to remove users from specific user groups.\n\n To remove users from user groups in a project for the administrating tenant, provide a project UUID in the `ProjectID` request header.\n Administrating tenants can remove users to user groups in multiple analytic tenants by providing a tenant code and project ID in the request body.\n\n We recommend that administrating tenants set the analytic tenant in which to execute the API call using the `TargetTenantID` request header."
operationId: UsersV1_RemoveUsersFromUserGroup
parameters:
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
- name: Prefer
in: header
description: 'When `NonVersioned: true`, use `Prefer` to optionally specify if API calls should be subject to locking. Locking prevents incremental changes in multiple API calls from overwriting each other. The `Prefer` header works alongside a tenant feature flag. When enabled, the default is `nvLock=global`. When disabled, the default is not to lock API calls. Contact Visier Technical Support to enable the tenant feature flag.
Valid values for the `Prefer` header:
* `nvLock=global`: Run API calls sequentially. Sequential API calls prevent calls from unintentionally overwriting each other.
* `nvLock=artifact`: Allow API calls in parallel. Parallel API calls only work if the calls do not conflict with each other. If a change wasn''t applied, the request fails and returns the HTTP 409 conflict error. Run the request again until successful.
* `nvLock=none`: Disable the global lock if the tenant feature flag is enabled.'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/admin.UsersToUserGroupsRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.SecurityAssignmentResponseDTO'
/v1/admin/user-groups/{userGroupId}/users:
get:
tags:
- UsersV1
summary: Retrieve a list of user group users
description: "This API allows you to retrieve the list of users explicitly assigned to a user group. Users that are implicitly\n included in the user group through the user group's dynamic filters are not returned by this endpoint.\n\n To specify the project in which to retrieve user group users for the login tenant, provide\n a project UUID in the `ProjectID` request header. If omitted, the request retrieves user group users from production."
operationId: UsersV1_GetUserGroupUsers
parameters:
- name: userGroupId
in: path
description: The ID of user group.
required: true
schema:
type: string
- name: tenantFilter
in: query
description: Specifies the tenant to retrieve the list of users from.
schema:
type: string
- name: limit
in: query
description: The number of results to return. The maximum number of tenants to retrieve is 100.
schema:
type: integer
format: uint32
- name: start
in: query
description: The index to start retrieving results from, also known as offset. The index begins at 0.
schema:
type: integer
format: uint32
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/admin.UserGroupsUsersDTO'
/v1/admin/users:
get:
tags:
- UsersV1
summary: Retrieve a list of all users
description: "This API allows you to retrieve the full list of users and their current states.\n\n To specify the project in which to retrieve user information, provide a project UUID in the `ProjectID` request header. If omitted, the request retrieves user information from production."
operationId: UsersV1_GetAllUsers
parameters:
- name: tenantCode
in: query
description: Specify the tenant to retrieve a list of users from.
schema:
type: string
- name: assignedProfiles
in: query
description: If true, the response returns a list of the user's assigned profiles.
schema:
type: boolean
- name: assignedPermissions
in: query
description: If true, the response returns the user's assigned permissions.
schema:
type: boolean
- name: assignedUserGroups
in: query
description: If true, the response returns the user's assigned user groups.
schema:
type: boolean
- name: limit
in: query
description: The number of results to return. The maximum number of users to retrieve is 1000.
schema:
type: integer
format: uint32
- name: start
in: query
description: The index to start retrieving results from, also known as offset. The index begins at 0.
schema:
type: integer
format: uint32
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.AllUsersGetAPIResponseDTO'
post:
tags:
- UsersV1
summary: Add a user
description: Create a new user. Administrating tenant users can specify the tenant in which to add a user.
operationId: UsersV1_AddUser
parameters:
- name: tenantCode
in: query
description: Specify the tenant to create a user in.
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.UserCreationAPIRequestDTO'
required: true
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreationAPIResponseDTO'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/admin/users/{userId}:
get:
tags:
- UsersV1
summary: Retrieve a user's details
description: "This API allows you to retrieve all details for a specified user.\n\n To specify the project in which to retrieve user information, provide a project UUID in the `ProjectID` request header. If omitted, the request retrieves user information from production."
operationId: UsersV1_GetUserDetail
parameters:
- name: userId
in: path
description: The ID of the user you want to retrieve.
required: true
schema:
type: string
- name: tenantCode
in: query
description: Specify the tenant to retrieve a user from.
schema:
type: string
- name: assignedProfiles
in: query
description: If true, the response returns a list of the user's assigned profiles.
schema:
type: boolean
- name: assignedPermissions
in: query
description: If true, the response returns the user's assigned permissions.
schema:
type: boolean
- name: assignedUserGroups
in: query
description: If true, the response returns the user's assigned user groups.
schema:
type: boolean
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: NonVersioned
in: header
description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
schema:
type: boolean
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.UserGetAPIResponseDTO'
put:
tags:
- UsersV1
summary: Update a user
description: Update an existing user's information, such as their display name or if the user is enabled in Visier.
operationId: UsersV1_UpdateUser
parameters:
- name: userId
in: path
description: The ID of the user you want to update.
required: true
schema:
type: string
- name: tenantCode
in: query
description: Specify the tenant to update a user in.
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.UserUpdateAPIRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.UserUpdateAPIRequestDTO'
delete:
tags:
- UsersV1
summary: Delete a user
description: Delete an existing user. Administrating tenant users can specify the tenant from which to delete a user.
op
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-usersv1-api-openapi.yml