User authentication tokens¶
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.
Managing tokens¶
Get 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.
New in version 4.14.
Query Parameters: - seconds – The duration of the token.
- autoRefresh –
false
(default) - The token always expires afterseconds
seconds after the token was created.true
- (New in 4.2.2.) The expiration clock is reset with every API call.
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>
Get 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 – The duration of the token.
- autoRefresh –
false
(default) - The token always expires afterseconds
seconds after the token was created.true
- The expiration clock is reset with every API call.
Status Codes: - 409 Conflict – The user is disabled.
Produces: - text/plain – The generated token.
Changed in version 4.14: HTTP 409 is now returned when trying to create a token for a disabled user.
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.
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.