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
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 – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
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
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¶
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, see Retrieve the salt of a 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, see Retrieve the salt of a 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
Get an authentication token for a user¶
- GET /user/(username)/token¶
Creates a authentication for a user. This token can be used for calling the API without specifying username or password.
Query Parameters: - seconds – The duration of the token.
- autoRefresh –
- false (default) - The token always expires after seconds seconds after the token was created.
- true - (New in 4.2.2.) The expiration clock is reset with every API call.
Produces: - text/plain – The generated token.
Semantics¶
Calling this API resource will generate an authentication token. The username path parameter must match the calling user’s credentials, unless the calling user has _administrator role. The token always has an expiration time.
New in version 4.2.2.
The rules for the expiration time depends on configuration property userTokenMaxInterval (default 60 seconds):
- Not specified -
The token expires after the time entered in the configuration property userTokenDefaultInterval (default 60 seconds)
- Less than or equal to userTokenMaxInterval -
Always allowed
- Greater than userTokenMaxInterval -
Only allowed if the calling user has _administrator role.
If autoRefresh is true, the expiration clock is reset with every API call when the token is used, with one exception. If the time since last reset is less than configuration property userTokenRefreshInterval (default 10 seconds), the token is not updated. This is in order to reduce database writes. Example:
- Token is created, will expire in 60 seconds.
- 8 seconds later, token is used. Since 8<10, token is not updated.
- Another 8 seconds later, token is used again. Since 16>10, token is updated, and valid for 60 seconds more.
Example¶
(Note, this call above is invoked by user admin)
GET /user/myuser/token
Authorization: basic YWRtaW46YWRtaW4=
6663e105-828e-45c1-ac54-7dd17f3e8a38
GET /item
Authorization: token 6663e105-828e-45c1-ac54-7dd17f3e8a38
This will return items that user myuser has access to.
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 with allgroups=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 relations
- false (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