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:
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:
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 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

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:
Produces:
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

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:

_administrator

Change 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

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

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

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:

  1. Token is created, will expire in 60 seconds.
  2. 8 seconds later, token is used. Since 8<10, token is not updated.
  3. 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:
Role:

_administrator

Retrieve a list of roles a user has

GET /user/(username)/roles

Returns a list of all the roles a user has.

Produces:
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:
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:
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

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