@itslanguage/api

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>api/authentication - ITSLanguage JavaScript SDK</title> <meta name="description" content="Speech technology for language education. JSDoc 3 website for the JavaScript SDK." /> <meta name="keywords" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta name="keyword" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta property="og:title" content="ITSLanguage JavaScript SDK"/> <meta property="og:type" content="website"/> <meta property="og:image" content="https://avatars0.githubusercontent.com/u/20972344?s=400&u=73936e7fa2d2a1e5c180a11675bf9166d3717a6d&v=4"/> <meta property="og:site_name" content="ITSLanguage JavaScript SDK"/> <meta property="og:url" content="http://itslanguage.github.io/itslanguage-js/"/> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav > <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/itslanguage/itslanguage-js" target="_blank" class="menu-item" id="repository" >Github repo</a></h2><h3>Modules</h3><ul><li><a href="module-api.html">api</a><ul class='members'><li data-type='member'><a href="module-api.html#.version">version</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api.html#.createItslApi">createItslApi</a></li></ul></li><li><a href="module-api_authentication.html">api/authentication</a><ul class='methods'><li data-type='method'><a href="module-api_authentication.html#.assembleScope">assembleScope</a></li><li data-type='method'><a href="module-api_authentication.html#.authenticate">authenticate</a></li><li data-type='method'><a href="module-api_authentication.html#.impersonate">impersonate</a></li></ul></li><li><a href="module-api_basicauth.html">api/basicauth</a><ul class='methods'><li data-type='method'><a href="module-api_basicauth.html#.create">create</a></li></ul></li><li><a href="module-api_broadcaster.html">api/broadcaster</a></li><li><a href="module-api_categories.html">api/categories</a><ul class='methods'><li data-type='method'><a href="module-api_categories.html#.create">create</a></li><li data-type='method'><a href="module-api_categories.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_categories.html#.getAllWithParentId">getAllWithParentId</a></li><li data-type='method'><a href="module-api_categories.html#.getById">getById</a></li><li data-type='method'><a href="module-api_categories.html#.update">update</a></li></ul></li><li><a href="module-api_challenges.html">api/challenges</a><ul class='members'><li data-type='member'><a href="module-api_challenges.html#.choice">choice</a></li><li data-type='member'><a href="module-api_challenges.html#.choiceRecognition">choiceRecognition</a></li><li data-type='member'><a href="module-api_challenges.html#.feedback">feedback</a></li><li data-type='member'><a href="module-api_challenges.html#.feedbackSpeech">feedbackSpeech</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciation">pronunciation</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciationAnalysis">pronunciationAnalysis</a></li><li data-type='member'><a href="module-api_challenges.html#.speech">speech</a></li><li data-type='member'><a href="module-api_challenges.html#.speechRecording">speechRecording</a></li></ul></li><li><a href="module-api_challenges_choice.html">api/challenges/choice</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_choice_recognition.html">api/challenges/choice/recognition</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recognise">recognise</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseAudioStream">recogniseAudioStream</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseNonStreaming">recogniseNonStreaming</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_feedback.html">api/challenges/feedback</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_feedback_speech.html">api/challenges/feedback/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.feedback">feedback</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.listenAndReply">listenAndReply</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.pause">pause</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.resume">resume</a></li></ul></li><li><a href="module-api_challenges_pronunciation.html">api/challenges/pronunciation</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.deleteChallenge">deleteChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_pronunciation_analysis.html">api/challenges/pronunciation/analysis</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.alignChallenge">alignChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.endStreamAudio">endStreamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareAudio">prepareAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.streamAudio">streamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_speech.html">api/challenges/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_speech_recordings.html">api/challenges/speech/recordings</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.record">record</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#~url">url</a></li></ul></li><li><a href="module-api_communication.html">api/communication</a><ul class='members'><li data-type='member'><a href="module-api_communication.html#.settings">settings</a></li><li data-type='member'><a href="module-api_communication.html#~APPLICATION_JSON">APPLICATION_JSON</a></li><li data-type='member'><a href="module-api_communication.html#~AUTHORIZATION">AUTHORIZATION</a></li><li data-type='member'><a href="module-api_communication.html#~CONTENT_TYPE">CONTENT_TYPE</a></li><li data-type='member'><a href="module-api_communication.html#~LINK">LINK</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api_communication.html#.addAccessToken">addAccessToken</a></li><li data-type='method'><a href="module-api_communication.html#.authorisedRequest">authorisedRequest</a></li><li data-type='method'><a href="module-api_communication.html#.request">request</a></li><li data-type='method'><a href="module-api_communication.html#.updateSettings">updateSettings</a></li><li data-type='method'><a href="module-api_communication.html#~getBearerToken">getBearerToken</a></li><li data-type='method'><a href="module-api_communication.html#~handleResponse">handleResponse</a></li></ul></li><li><a href="module-api_communication_websocket.html">api/communication/websocket</a><ul class='methods'><li data-type='method'><a href="module-api_communication_websocket.html#.closeWebsocketConnection">closeWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.getWebsocketConnection">getWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.makeWebsocketCall">makeWebsocketCall</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.openWebsocketConnection">openWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~establishNewBundesbahn">establishNewBundesbahn</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~handleWebsocketAuthorisationChallenge">handleWebsocketAuthorisationChallenge</a></li></ul></li><li><a href="module-api_emailauth.html">api/emailauth</a><ul class='methods'><li data-type='method'><a href="module-api_emailauth.html#.create">create</a></li><li data-type='method'><a href="module-api_emailauth.html#~url">url</a></li></ul></li><li><a href="module-api_groups.html">api/groups</a><ul class='methods'><li data-type='method'><a href="module-api_groups.html#.create">create</a></li><li data-type='method'><a href="module-api_groups.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_groups.html#.getById">getById</a></li></ul></li><li><a href="module-api_organisations.html">api/organisations</a><ul class='methods'><li data-type='method'><a href="module-api_organisations.html#.create">create</a></li><li data-type='method'><a href="module-api_organisations.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_organisations.html#.getById">getById</a></li></ul></li><li><a href="module-api_profile.html">api/profile</a><ul class='methods'><li data-type='method'><a href="module-api_profile.html#.create">create</a></li><li data-type='method'><a href="module-api_profile.html#.getById">getById</a></li><li data-type='method'><a href="module-api_profile.html#.getCurrent">getCurrent</a></li><li data-type='method'><a href="module-api_profile.html#~url">url</a></li></ul></li><li><a href="module-api_progress.html">api/progress</a><ul class='methods'><li data-type='method'><a href="module-api_progress.html#.getById">getById</a></li></ul></li><li><a href="module-api_roles.html">api/roles</a><ul class='methods'><li data-type='method'><a href="module-api_roles.html#.create">create</a></li><li data-type='method'><a href="module-api_roles.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_roles.html#.getById">getById</a></li></ul></li><li><a href="module-api_tenants.html">api/tenants</a><ul class='methods'><li data-type='method'><a href="module-api_tenants.html#.create">create</a></li><li data-type='method'><a href="module-api_tenants.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_tenants.html#.getById">getById</a></li></ul></li><li><a href="module-api_users.html">api/users</a><ul class='methods'><li data-type='method'><a href="module-api_users.html#.create">create</a></li><li data-type='method'><a href="module-api_users.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_users.html#.getById">getById</a></li><li data-type='method'><a href="module-api_users.html#.getCurrent">getCurrent</a></li></ul></li><li><a href="module-api_utils.html">api/utils</a><ul class='methods'><li data-type='method'><a href="module-api_utils.html#.asyncBlobToArrayBuffer">asyncBlobToArrayBuffer</a></li><li data-type='method'><a href="module-api_utils.html#.checkAudioIsNotEmpty">checkAudioIsNotEmpty</a></li><li data-type='method'><a href="module-api_utils.html#.dataToBase64">dataToBase64</a></li></ul></li><li><a href="module-api_utils_audio-over-socket.html">api/utils/audio-over-socket</a><ul class='methods'><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.encodeAndSendAudioOnDataAvailable">encodeAndSendAudioOnDataAvailable</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.prepareServerForAudio">prepareServerForAudio</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.registerStreamForRecorder">registerStreamForRecorder</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-api.Itslanguage.html">Itslanguage</a></li></ul><h3>Events</h3><ul><li><a href="broadcaster.html#event:websocketserverreadyforaudio">websocketserverreadyforaudio</a></li></ul> </nav> <div id="main"> <h1 class="page-title">api/authentication</h1> <section> <header> </header> <article> <div class="container-overview"> <div class="description"><p>This file contains a set of functions which makes authentication easier.</p></div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="auth_index.js.html">auth/index.js</a>, <a href="auth_index.js.html#line1">line 1</a> </li></ul></dd> <dt class="tag-see">See:</dt> <dd class="tag-see"> <ul> <li><a href="https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html">https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html</a></li> </ul> </dd> </dl> </div> <h3 class="subsection-title">Methods</h3> <h4 class="name" id=".assembleScope"><span class="type-signature">(static) </span>assembleScope<span class="signature">(tenant<span class="signature-attributes">opt</span>, organisation<span class="signature-attributes">opt</span>, user<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string}</span></h4> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="auth_index.js.html">auth/index.js</a>, <a href="auth_index.js.html#line29">line 29</a> </li></ul></dd> <dt class="tag-see">See:</dt> <dd class="tag-see"> <ul> <li><a href="https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html#impersonation">https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html#impersonation</a></li> </ul> </dd> </dl> <div class="description"> <p>Assemble the scope form the given individual pieces.</p> <p>The scope is used to identify what the authenticated is allowed to do. It can slo be used by admin and tenant users to impersonate as a tenant, organisation or user.</p> <p>Keep in mind that in order to specify the user, the scope also needs to be specified.</p> </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th>Attributes</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>tenant</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>The ID of the tenant which is requesting this scope.</p></td> </tr> <tr> <td class="name"><code>organisation</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>The ID of the organisation which is requesting this scope.</p></td> </tr> <tr> <td class="name"><code>user</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>The ID of the user which is requesting this scope.</p></td> </tr> </tbody> </table> <h5>Throws:</h5> <dl> <dt> <div class="param-desc"> <ul> <li>When no arguments are provided.</li> </ul> </div> </dt> <dd></dd> <dt> <dl class="param-type"> <dt> Type </dt> <dd> <span class="param-type">Error</span> </dd> </dl> </dt> <dd></dd> </dl> <h5>Returns:</h5> <div class="param-desc"> <ul> <li>The assembled scope.</li> </ul> </div> <dl class="param-type"> <dt> Type </dt> <dd> <span class="param-type">string</span> </dd> </dl> <h4 class="name" id=".authenticate"><span class="type-signature">(static) </span>authenticate<span class="signature">(username, password, scope<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Promise}</span></h4> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="auth_index.js.html">auth/index.js</a>, <a href="auth_index.js.html#line105">line 105</a> </li></ul></dd> </dl> <div class="description"> <p>Authenticate for the given credentials with the given scope.</p> <p>On a successful authentication, the settings are updated so every follow-up API requests is authorized by the currently authenticated user.</p> </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th>Attributes</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>username</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> </td> <td class="description last"><p>The username to authenticate with.</p></td> </tr> <tr> <td class="name"><code>password</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> </td> <td class="description last"><p>The password to authenticate with.</p></td> </tr> <tr> <td class="name"><code>scope</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>The scope of the authentication. Omitting this value will cause the API to infer the scope.</p></td> </tr> </tbody> </table> <h5>Returns:</h5> <div class="param-desc"> <ul> <li>A promise which will resolve if the authentication concluded successfully, it'll reject in any other case. It resolves with the response body of the token request.</li> </ul> </div> <dl class="param-type"> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> <h4 class="name" id=".impersonate"><span class="type-signature">(static) </span>impersonate<span class="signature">(scope<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Promise}</span></h4> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="auth_index.js.html">auth/index.js</a>, <a href="auth_index.js.html#line76">line 76</a> </li></ul></dd> <dt class="tag-see">See:</dt> <dd class="tag-see"> <ul> <li><a href="https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html#impersonation">https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html#impersonation</a></li> </ul> </dd> </dl> <div class="description"> <p>Impersonate some other tenant, user or organisation. The impersonation will be done by using the authorisation token for the current user.</p> <p>On a successful impersonation, the settings are updated so every follow-up API requests is authorized by the access_token required with this impersonation.</p> <p>As an admin or tenant user it is possible to do impersonation. This goes from top to down. So, a tenant user can impersonate an organisation, or an user in an organisation. But an user can't impersonate.</p> </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th>Attributes</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>scope</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>The scope of the impersonation. Omitting this value will cause the API to return a token for the current user.</p></td> </tr> </tbody> </table> <h5>Returns:</h5> <div class="param-desc"> <ul> <li>A promise which will resolve if the authentication concluded successfully, it'll reject in any other case. It resolves with the response body of the token request.</li> </ul> </div> <dl class="param-type"> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> </article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Mon Oct 12 2020 12:26:34 GMT+0000 (Coordinated Universal Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script>prettyPrint();</script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>