Extend documentation for using organizations

EXAMPLES.md

@@ -48,6 +48,42 @@ if (organization && invitation) {
 }
 ```
 
+### Storing the organization
+
+When working with organizations, you might want to store the organization to ensure subsequent renewals of tokens using `checkSession` do not lose the context of the last used organization.
+
+```js
+auth0.parseHash({}, ({ idTokenPayload }) => {
+  var organization = idTokenPayload.org_id || idTokenPayload.org_name;
+
+  // store organization somewhere that persists across page-refreshes
+  // - localstorage
+  // - cookie
+  localStorage.setItem('app_organization', organization);
+});
+```
+
+With the organization stored in a persistent storage, you want to ensure it's always pulled in from there when calling `checkSession`:
+
+```js
+webAuth.checkSessions(
+  {
+    organization: localStorage.setItem('app_organization')
+  },
+  () => {}
+);
+```
+
+Additionally, you also want to ensure to read the last used organization when instantiating `WebAuth` on every subsequent page refresh.
+
+```js
+var webAuth = new WebAuth({
+  domain: '{YOUR_AUTH0_DOMAIN}',
+  clientID: '{YOUR_AUTH0_CLIENT_ID}',
+  organization: localStorage.setItem('app_organization')
+});
+```
+
 ## WebAuth.client.login(options, callback)
 
 Authenticates a user with username and password in a realm using `/oauth/token`. This will not initialize a SSO session at Auth0, hence can not be used along with silent authentication.

src/web-auth/index.js

@@ -674,6 +674,7 @@ WebAuth.prototype.renewAuth = function (options, cb) {
  * @param {String} [options.scope] scopes to be requested during Auth. e.g. `openid email`
  * @param {String} [options.audience] identifier of the resource server who will consume the access token issued after Auth
  * @param {String} [options.timeout] value in milliseconds used to timeout when the `/authorize` call is failing as part of the silent authentication with postmessage enabled due to a configuration.
+ * @param {String} [options.organization] the id or name of an organization to log in to
  * @param {checkSessionCallback} cb
  * @see {@link https://auth0.com/docs/libraries/auth0js/v9#using-checksession-to-acquire-new-tokens}
  * @memberof WebAuth.prototype

test/web-auth/web-auth.test.js

@@ -3044,6 +3044,22 @@ describe('auth0.WebAuth', function () {
       });
       this.auth0.checkSession({}, function (err, data) {});
     });
+
+    it('inits IframeHandler with organization', function (done) {
+      sinon.stub(IframeHandler.prototype, 'init').callsFake(function () {
+        expect(this.url).to.be(
+          'https://me.auth0.com/authorize?client_id=...&response_type=token&redirect_uri=http%3A%2F%2Fpage.com%2Fcallback&organization=org_123&from=transaction-manager&response_mode=web_message&prompt=none'
+        );
+        expect(this.eventListenerType).to.be('message');
+        expect(this.timeout).to.be(60000);
+        done();
+      });
+      this.auth0.checkSession(
+        { organization: 'org_123' },
+        function (err, data) {}
+      );
+    });
+
     it('uses custom timeout when provided', function (done) {
       var timeout = 1;
       sinon.stub(IframeHandler.prototype, 'init').callsFake(function () {