Users¶
Managing users¶
Retrieve a list of all users¶
-
GET
/user
¶ Retrieves a list of all known users.
Query Parameters: - name – List of user names to return information about. Default is all users.
- first – Start returning users from specified number. Default is
1
, the beginning of the list. - number – Return at most specified number of users. Default is no limit.
Produces: - application/xml, application/json – UserListDocument
Role: _administrator
Create a new user¶
-
POST
/user
¶ Creates a new user based on the information in the UserDocument.
Query Parameters: - passwordType –
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
- passwordType –
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 specific user¶
-
GET
/user/
(username)¶ Returns a specific user.
Produces: - application/xml, application/json – XML/JSON, schema UserDocument
Role: _administrator
Create a new 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¶
New in version 4.14.
-
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 –
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
- passwordType –
Caution
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 –
If set to
true
, the user will be removed completely. Else the user will be disabled.New in version 4.6.
- notification – The placeholder job notification to use for this job. (Optional)
- notificationData – Any additional data to include for notifications on this job. (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task.
Produces: - application/xml, application/json – XML/JSON, schema JobDocument if
hard=true
Role: _administrator
- hard –
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¶
New in version 4.0.
-
PUT
/user
¶ Simple search of fields
username
,realname
and metadata.Query Parameters: - number – Return at most specified number of users. Default is
10
.
Accepts: - application/xml, application/json – UserSearchDocument
Produces: - application/xml, application/json – UserListDocument
- text/plain – CRLF-delimited list of Tabbed tuples: username, realname, groups*
Role: _administrator
- number – Return at most specified number of users. Default is
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
and realname
are reserved to do search on
username
and realname
fields
The boolean operators AND 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>
User information¶
Key-value metadata¶
Users support key-value metadata.
User credentials¶
Change 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 –
raw
- Password is in plaintext.md5
(default) - Password is already hashed.
Accepts: - text/plain – The new password.
Role: _administrator
- type –
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.
Any hashed passwords need to be salted using the salt of the user.
Query Parameters: - type –
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
- type –
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¶
Retrieve a list of groups a user belongs to¶
-
GET
/user/
(username)/groups
¶ Retrieves a list of all the groups a user belongs to.
Query Parameters: - allgroups –
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 –
true
- When used in combination withallgroups=true
, the groups’ hierarchies are shown.false
(default) - List the groups without hierarchical ordering.
Produces: - application/xml, application/json – GroupListDocument
Role: _administrator
- allgroups –
Retrieve a list of roles a user has¶
-
GET
/user/
(username)/roles
¶ Returns a list of all the roles a user has.
Produces: - application/xml, application/json – GroupListDocument
Role: _administrator
Retrieve all the 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: _administrator
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 –
true
- Remove all previous group-to-user relationsfalse
(default) - Keep the current group-to-user relations, and add the specified list
Accepts: - application/xml, application/json – GroupListDocument
Role: _administrator
- move –
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¶
New in version 4.1.2.
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.
Get user graph¶
-
GET
/user/graph
¶ Shows the relationships of users and groups.
Query Parameters: - users – Comma-separated list of users to include. Default is all users.
- groups – Comma-separated list of groups to include. Default is all groups.
Produces: - image/png –
Role: _administrator
Get 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 – Comma-separated list of users to include. Default is all users.
- groups – Comma-separated list of groups to include. Default is all groups.
Produces: - text/plain, text/vnd.graphviz –
Role: _administrator