User reference [VC 21.3.1 GEN]

Manage users.

Managing users

List all users

GET /user

Retrieves a list of all known users.

Query Parameters:	name (string[]) – List of user names to return information about. Default is all users. disabled (string) – If `true` only disabled users are shown, if `false` only enabled users are shown. Default is `all` - all users are shown. first (integer) – Start returning users from specified number. Default is `1`, the beginning of the list. number (integer) – Return at most specified number of users. Default is no limit.
Produces:	application/xml, application/json – UserListDocument
Role:	_user_read

Create a user

POST /user

Creates a new user based on the information in the UserDocument.

Query Parameters:	passwordType (string) – `raw` - Password is in plaintext. `md5` (default) - Password is already hashed.
Status Codes:	200 OK – User created. 409 Conflict – A user with that username already exists.
Accepts:	application/xml, application/json – UserDocument
Role:	_administrator

Example

POST /user?passwordType=raw
Content-Type: application/xml

<UserDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <userName>myuser</userName>
  <realName>My User</realName>
  <password>qwerty</password>
  <groupList>
    <group>
      <groupName>mygroup</groupName>
    </group>
  </groupList>
</UserDocument>

Retrieve a user

GET /user/(username)

Returns a specific user.

Produces:	application/xml, application/json – XML/JSON, schema UserDocument
Role:	_user_read

Create a user

PUT /user/(username)

Creates a new user with the given username.

Status Codes:	200 OK – User created. 409 Conflict – A user with that username already exists.
Role:	_administrator

Update a user

PUT /user/(username)

Updates a user based on the information in the UserDocument.

The username of a user can be changed by providing a different username in the given user document.

Query Parameters:	passwordType (string) – `raw` - Password is in plaintext. `md5` (default) - Password is already hashed.
Status Codes:	200 OK – User updated. 409 Conflict – A user with the new username already exists.
Accepts:	application/xml, application/json – UserDocument
Produces:	application/xml, application/json – UserDocument
Role:	_administrator

To reflect a username change in the search index a re-index operation on items and collections is required. See Re-indexing metadata.

Example

For example, to change the name and username of a user:

PUT /user/stephen@example.com
Content-Type: application/xml

<UserDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <userName>stephen</userName>
  <realName>Stephen</realName>
</UserDocument>

Disable a user

DELETE /user/(username)

Disables a user with the given username, rendering that user unable to login.

Query Parameters:	hard (boolean) – If set to `true`, the user will be removed completely, including all access controls granted by the user. Else the user will be disabled. Default is `false`. preserveAccess (boolean) – If set to `true`, the access granted by the user will still apply. Only applicable for `hard=false`. Default is `false`. New in version 4.17. transferAccess (string) – If set, the specified user assumes all access controls of the user being deleted, including ownership, granted, and received access. This avoids any access chains breaking. The modified access control entries can be found in the job document metadata, under the `transferredAccess` key. Only applicable for `hard=true`. New in version 5.3. notification (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is `MEDIUM` . jobmetadata (string[]) – Additional information for the job task.
Produces:	application/xml, application/json – XML/JSON, schema JobDocument if `hard=true`
Role:	_administrator

Re-enable a user

PUT /user/(username)/enable

Re-enables a user with the given username, that has previously been disabled.

Role:

_administrator

Search users

PUT /user

Simple search of fields username, realname, groupname and metadata.

Changed in version 5.1: Support for searching using groupname was added.

Query Parameters:	number (integer) – Return at most specified number of users. Default is `10`. first (integer) – Start returning users from specified number. Default is `1`, the beginning of the list. disabled (string) – If `true` only disabled users are shown, if `false` only enabled users are shown. Default is `all` - all users are shown. ignoreCase (boolean) – `true` - Perform a case insensitive search on the fields username, realname, groupname and metadata values. `false` (default) - Perform a case sensitive search. New in version 5.2.
Accepts:	application/xml, application/json – UserSearchDocument
Produces:	application/xml, application/json – UserListDocument text/plain – CRLF-delimited list of Tabbed tuples: `username`, `realname`, `groups*`
Role:	_user_read

Example

PUT /user
Content-Type: application/xml

<UserSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <field>
        <name>username</name>
        <value>vidi</value>
    </field>
    <field>
        <name>key</name>
        <value>value</value>
    </field>
</UserSearchDocument>

Note that keywords username, realname, disabled, groupname, preserveaccess, external, uuid, and origin are reserved for searches on the respective user properties.

The boolean operators AND, NOT, and OR are supported.

<UserSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <field>
        <name>username</name>
        <value>vidi</value>
    </field>
    <field>
        <name>realname</name>
        <value>vidispine</value>
    </field>
    <operator operation="OR">
        <field>
          <name>key1</name>
          <value>value1</value>
        </field>
        <field>
          <name>key2</name>
          <value>value2</value>
        </field>
    </operator>
</UserSearchDocument>

Note when searching for groupnames the result is filtered on matching groupnames, and when using NOT the rest of the search criterias is handled similare to an OR search.

User information

Key-value metadata

Users support key-value metadata.

Users can always read their own metadata, but the _user_metadata_write role is required to edit it. The _administrator role is required to read or write other user’s metadata.

Retrieve the real name of a user

GET /user/(username)/realname

Returns the real name of a user.

Produces:	text/plain – The real name of the user.
Role:	_user_read

See access control entries for user

New in version 5.4.

GET /user/(username)/access

Returns an AccessControlListDocument of all access entries that apply for the specified user. Entity type and entity id can be found in the loc field of the AccessControlDocument.

Query Parameters:	entityType (string) – The type of entity the access control applies to. One of `item`, `collection`, `library`, or `all`. Default is `all` - all entries are shown. level (string) – The Access levels that the access control grants. Default is all entries shown. number (integer) – Return at most specified number of entries. Default is all access controls. first (integer) – Start returning entries from specified number. Default is `1`, the beginning of the list.
Produces:	application/xml, application/json – AccessControlListDocument
Role:	_user_read (except for reading own access), _accesscontrol_read

Update the real name of a user

PUT /user/(username)/realname

Changes the real name of a user.

Accepts:	text/plain – The new name.
Role:	_administrator

User credentials

Update the password of a user

PUT /user/(username)/password

Changes the password for a user. Hashed passwords are assumed to be represented as hexadecimal strings.

Any hashed passwords need to be salted using the salt of the user.

Query Parameters:	type (string) – `raw` - Password is in plaintext. `md5` (default) - Password is already hashed.
Accepts:	text/plain – The new password.
Role:	_administrator

Validate the password of a user

PUT /user/(username)/validate

Validates the given password against the password of the user. Hashed passwords are assumed to be represented as hexadecimal strings. Another option to validate the user credentials is to call whoami.

Any hashed passwords need to be salted using the salt of the user.

Query Parameters:	type (string) – `raw` - Password is in plaintext. `md5` (default) - Password is hashed.
Status Codes:	200 OK – The password is correct. 403 Forbidden – The password is incorrect.
Accepts:	text/plain – The password of the user.
Produces:	text/plain – “OK <$PASSWORD>”
Role:	_administrator

Retrieve the salt of a user

GET /user/(username)/password/salt

Retrieves the salt of the specified user.

Status Codes:	200 – Salt is returned. 204 – No salt is set for the user.
Produces:	application/octet-stream – The salt of the user.
Role:	_administrator

Generate a salt for a user

POST /user/(username)/password/salt

Generates a new salt for the user, overwriting any existing salt.

Note that this will invalidate any set password for the user and requires a new password to be set for the user to be able to login. This method is typically not relevant if passwords are updated using plaintext.

Produces:	application/octet-stream – The salt of the user.
Role:	_administrator

Group-to-user relations

List all groups for a user

GET /user/(username)/groups

Retrieves a list of all the groups a user belongs to.

Query Parameters:	allgroups (boolean) – `true` - List all groups the user belongs to, including parent groups. `false` (default) - Just list the groups that the user is directly assigned to. traverse (boolean) – `true` - When used in combination with `allgroups=true`, the groups’ hierarchies are shown. `false` (default) - List the groups without hierarchical ordering.
Produces:	application/xml, application/json – GroupListDocument
Role:	_user_read

List all roles for a user

GET /user/(username)/roles

Returns a list of all the roles a user has.

Produces:	application/xml, application/json – GroupListDocument
Role:	_user_read

List all roles and groups for a user

GET /user/(username)/allgroups

Retrieves a list of all the groups a user belongs to, as well as all roles the user is in.

Produces:	application/xml, application/json – GroupListDocument
Role:	_user_read

Add a user to multiple groups

PUT /user/(username)/groups

Adds a to multiple to groups. If the move parameter is set to true, it will cause the user to be moved to the specified groups.

Query Parameters:	move (boolean) – `true` - Remove all previous group-to-user relations `false` (default) - Keep the current group-to-user relations, and add the specified list
Accepts:	application/xml, application/json – GroupListDocument
Role:	_administrator

Example

First the user belongs to a single group:

GET /user/myuser/groups

<GroupListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <groupName>A</groupName>
      <role>false</role>
   </group>
</GroupListDocument>

The user is then added to groups B, C:

PUT /user/myuser/groups
Content-Type: application/xml

<GroupListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <groupName>B</groupName>
   </group>
   <group>
      <groupName>C</groupName>
   </group>
</GroupListDocument>

GET /user/myuser/groups

<GroupListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <groupName>A</groupName>
      <role>false</role>
   </group>
   <group>
      <groupName>B</groupName>
      <role>false</role>
   </group>
   <group>
      <groupName>C</groupName>
      <role>false</role>
   </group>
</GroupListDocument>

And then moved to groups A, B:

PUT /user/myuser/groups?move=true
Content-Type: application/xml

<GroupListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <groupName>A</groupName>
   </group>
   <group>
      <groupName>B</groupName>
   </group>
</GroupListDocument>

GET /user/myuser/groups

<GroupListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <groupName>A</groupName>
      <role>false</role>
   </group>
   <group>
      <groupName>B</groupName>
      <role>false</role>
   </group>
</GroupListDocument>

User/group visualization

In order to easily see the dependencies between users and groups there is a functionality to render the user and group hierarchy as a graph. In order to render the graph, the Graphviz package is required.

Retrieve the user graph

GET /user/graph

Shows the relationships of users and groups.

Query Parameters:	users (string) – Comma-separated list of users to include. Default is all users. groups (string) – Comma-separated list of groups to include. Default is all groups. disabled (string) – If `true` only disabled users are shown, if `false` only enabled users are shown. Default is `all` - all users are shown.
Produces:	image/png –
Role:	_administrator

Retrieve the user graph as dot file

GET /user/graph/dot

Shows the relationships of users and groups in dot format, for further processing.

Query Parameters:	users (string) – Comma-separated list of users to include. Default is all users. groups (string) – Comma-separated list of groups to include. Default is all groups. disabled (string) – If `true` only disabled users are shown, if `false` only enabled users are shown. Default is `all` - all users are shown.
Produces:	text/plain, text/vnd.graphviz –
Role:	_administrator