User authentication tokens [VC 21.3.1 GEN]

User authentication tokens are short-lived tokens that can be used to authenticate a user. All tokens expire after a certain duration, but may auto-refresh on use to increase the expiration time of the token.

Token expiration

The rules for the expiration time depends on configuration property userTokenMaxInterval (default 60 seconds). If the expiration time is:

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.

Managing tokens

Retrieve an authentication token

GET /token

Creates a authentication token for the calling user. This token can be used for calling the API without specifying username or password.

Useful when users authenticate using an alias and the actual username of the user is not known.

Query Parameters:	seconds (integer) – The duration of the token. autoRefresh (boolean) – true - The expiration clock is reset with every API call. false (default) - The token always expires after seconds seconds after the token was created.
Status Codes:	409 Conflict – The user is disabled.
Produces:	application/xml, application/json – AuthenticationTokenDocument: The generated token. text/plain – The generated token.

Example

GET /token
Authorization: basic YWRtaW46YWRtaW4=

<AuthenticationTokenDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <token>5ay6Fxq2fFnmtVhrQq2owDvX0FE/RmdQG4SkefvW</token>
  <user>admin</user>
</AuthenticationTokenDocument>

Retrieve an authentication token for a specific user

GET /user/(username)/token

Creates a authentication token for a user. This token can be used for calling the API without specifying username or password.

The username path parameter must match the calling user’s credentials, unless the calling user has _administrator role.

Query Parameters:	seconds (integer) – The duration of the token. autoRefresh (boolean) – true - The expiration clock is reset with every API call. false (default) - The token always expires after seconds seconds after the token was created.
Status Codes:	409 Conflict – The user is disabled.
Produces:	text/plain – The generated token.

Example

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.