Vidispine
User authentication tokens [VC 21.3 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:
-
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.
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 afterseconds
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 afterseconds
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.