Login API
The Login API is used to allow authenticated users on your website to automatically be logged into the SecureVideo.com application, where they can schedule sessions, add and remove participants, send reminders, install the videoconferencing app, view participant presence, and initiate sessions.
For the most integrated look and feel, we recommend doing the following:
- Request that your API account be set up with the "Limit UI to Launch Panel Only" option enabled
- Use the Branding tab under Features to include your website's subdomain, logo, colors, and navigation menu
If you do this, then when your users are taken to our site, it will have a ton of functionality that is already well-tested and would be time-consuming for you to code, yet it will appear to almost every user to still be a part of your website.
There are 2 API methods available in the Login API:
Get Login URI
POST https://api.securevideo.com/login/5 (where 5 is the SecureVideo.com User ID); or,
POST https://api.securevideo.com/login/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
{
"RedirectToUriOnExpiry": "https://www.mywebsite.com/HandleSecureVideoLoginExpiration"
}
This is a server-to-server call which returns a URI which, when you direct your user's browser to it using javascript's "window.location.href = " or the like, will automatically log her in and redirect her to SecureVideo.com. Once the user's SecureVideo.com authentication expires, either through timeout or explicit logout, she will be redirected to the RedirectToUriOnExpiry URI that you specify.
The returned login URI will be in JSON, for example:
{
"LoginGuid": "e1579430ba1471ba8d4c0b2b6e8ba8d6",
"RedirectToUriOnExpiry": "https://www.mywebsite.com/HandleSecureVideoLoginExpiration",
"LoginUri": "https://hub.securevideo.com/Account/AutoLogin/auto=e1579430ba1471ba8d4c0b2b6e8ba8d6"
}
If you want to cancel the user's login for any reason after you have authorized it, you should retain the LoginGuid and call the Delete Login URI method with the LoginGuid (this is rare). Once a user is logged in, if you wish to programmatically log them out through their browser script please see the Manual Logout procedure below.
For security reasons, you must perform the redirect within 15 seconds of obtaining the Login URI, and you can only use the Login URI one time. By default, users are logged out of SecureVideo.com after 240 minutes of server inactivity, however API customers can request this to be changed by contacting SecureVideo support.
In order to provide a user with an automatic login, that user must already be a user within SecureVideo.com. Therefore, the general usage pattern is to create and update the SecureVideo.com user (using the User API) at the time you create and update your website users, and save the SecureVideo.com user ID in your user record. Then, when it is time to perform the automatic login, you use the SecureVideo.com user ID from the user record to perform the login.
Delete Login URI
DELETE https://api.securevideo.com/login/e1579430ba1471ba8d4c0b2b6e8ba8d6 (where e1579430ba1471ba8d4c0b2b6e8ba8d6 is the Login GUID obtained in the Get Login URI method)
Expires the login URI immediately.
On success, this request will return a 204 Status Code, indicating No Content.
Manual Logout
After you have logged a user into SecureVideo from your portal application via the Get Login URI, if the user returns to your portal application and, once there either logs out affirmatively or has their session on your portal time out, you may wish to ensure they are also logged out of SecureVideo. Because login state is held only on the user's browser using secure http-only cookies, to manually log a user out of SecureVideo you must direct the user's browser to the SecureVideo logout URL--there is no API call necessary (or possible) to do this as the SecureVideo servers do not contain any reference to any specific logged-in browser(s).
The proper SecureVideo logout URL to use is /Account/LogOffAndRedirect, using a query string parameter redirectToUrl which is the URL you would like to return the user to after logout. It is necessary to redirect the user to your SecureVideo subdomain to perform the logout as this is the only way the login cookie can be immediately invalidated. (Due to CORS restrictions, it is not possible to use an AJAX method to do this.) The below sample javascript is appropriate to perform a Manual Logout:
<script>
// Log the user out from SecureVideo. SecureVideo will issue a redirect that will send the user to the portal page https://your.portal.com/SomeEndpoint
// Be sure to use the correct subdomain in this code, otherwise the logout will fail
window.location.href = "https://yoursubdomain.securevideo.com/Account/LogOffAndRedirect?redirectToUrl=https://your.portal.com/SomeEndpoint";
</script>
If you do not specify the query string parameter redirectToUrl and you logged the user in via a Login URL obtained from the API, then the user will be redirected to the RedirectToUriOnExpiry that was returned by the API. If you do not specify the query string parameter redirectToUrl and you did not log the user in via a Login URL, then the user will be redirected to the SecureVideo login screen.
Please note that Manual Logout is on a per device basis. If a user has logged into SecureVideo simultaneously using multiple devices, to completely log them out from all devices, you would need to perform a Manual Logout on each device.
This article was last reviewed by our Support team on September 15, 2020.
