Adding warning about login_required when calling renewAuth in the docs

README.md

@@ -125,6 +125,8 @@ For this request to succeed, the user must have an active SSO session at Auth0 b
 
 > ***Important:*** this will use postMessage to communicate between the silent callback and the SPA. When false the SDK will attempt to parse the url hash should ignore the url hash and no extra behaviour is needed.
 
+> **Also important:** If you're not using the hosted login page to do social logins, you have to use your own [social connection keys](https://manage.auth0.com/#/connections/social). If you use Auth0's dev keys, you'll always get `login_required` as an error when calling `renewAuth`.
+
 It is strongly recommended to have a dedicated callback page for silent authentication in order to avoid loading your entire application again inside an iframe.
 This callback page should only parse the URL hash and post it to the parent document so that your application can take action depending on the outcome of the silent authentication attempt.
 For example:
@@ -150,18 +152,6 @@ For example:
 
 Remember to add the URL of the silent authentication callback page to the "Allowed Callback URLs" list of your Auth0 client.
 
-- **login(options, cb)**: Authenticates a user with username and password using `/co/authenticate`.
-```js
-webAuth.login({
-  username: 'username',
-  password: 'password',
-  redirectURI: 'https://localhost:3000/example/'
-  }, function(authError) {
-    // This callback is only invoked on authorization errors (`access_denied`)
-  });
-});
-```
-
 - **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.
 
 ```js

src/web-auth/cross-origin-authentication.js

@@ -28,15 +28,16 @@ function createKey(origin, coId) {
 }
 
 /**
- * Logs in the user with username and password using the cross origin authentication flow. You can use either `username` or `email` to identify the user, but `username` will take precedence over `email`.
+ * Logs in the user with username and password using the cross origin authentication (/co/authenticate) flow. You can use either `username` or `email` to identify the user, but `username` will take precedence over `email`.
+ * This only works when 3rd party cookies are enabled in the browser. After the /co/authenticate call, you'll have to use the {@link parseHash} function at the `redirectUri` specified in the constructor.
  *
  * @method login
  * @param {Object} options options used in the {@link authorize} call after the login_ticket is acquired
  * @param {String} [options.username] Username (mutually exclusive with email)
  * @param {String} [options.email] Email  (mutually exclusive with username)
  * @param {String} options.password Password
  * @param {String} [options.realm] Realm used to authenticate the user, it can be a realm name or a database connection name
- * @param {crossOriginLoginCallback} cb Callback function called only when an authentication error occurs. Has the error as the only parameter
+ * @param {crossOriginLoginCallback} cb Callback function called only when an authentication error, like invalid username or password, occurs. For other types of errors, there will be a redirect to the `redirectUri`.
  */
 CrossOriginAuthentication.prototype.login = function (options, cb) {
   var _this = this;

src/web-auth/index.js

@@ -207,6 +207,7 @@ WebAuth.prototype.validateToken = function (token, nonce, cb) {
 /**
  * Executes a silent authentication transaction under the hood in order to fetch a new tokens for the current session.
  * This method requires that all Auth is performed with {@link authorize}
+ * Watch out! If you're not using the hosted login page to do social logins, you have to use your own [social connection keys](https://manage.auth0.com/#/connections/social). If you use Auth0's dev keys, you'll always get `login_required` as an error when calling this method.
  *
  * @method renewAuth
  * @param {Object} options
@@ -313,7 +314,8 @@ WebAuth.prototype.signup = function (options, cb) {
 };
 
 /**
- * Redirects to the hosted login page (`/authorize`) in order to start a new authN/authZ transaction
+ * Redirects to the hosted login page (`/authorize`) in order to start a new authN/authZ transaction.
+ * After that, you'll have to use the {@link parseHash} function at the specified `redirectUri`.
  *
  * @method authorize
  * @param {Object} options
@@ -386,15 +388,16 @@ WebAuth.prototype.signupAndAuthorize = function (options, cb) {
  */
 
 /**
- * Logs in the user with username and password using the cross origin authentication flow. You can use either `username` or `email` to identify the user, but `username` will take precedence over `email`.
+ * Logs in the user with username and password using the cross origin authentication (/co/authenticate) flow. You can use either `username` or `email` to identify the user, but `username` will take precedence over `email`.
+ * This only works when 3rd party cookies are enabled in the browser. After the /co/authenticate call, you'll have to use the {@link parseHash} function at the `redirectUri` specified in the constructor.
  *
  * @method login
  * @param {Object} options options used in the {@link authorize} call after the login_ticket is acquired
  * @param {String} [options.username] Username (mutually exclusive with email)
  * @param {String} [options.email] Email  (mutually exclusive with username)
  * @param {String} options.password Password
  * @param {String} [options.realm] Realm used to authenticate the user, it can be a realm name or a database connection name
- * @param {crossOriginLoginCallback} cb Callback function called only when an authentication error occurs. Has the error as the only parameter
+ * @param {crossOriginLoginCallback} cb Callback function called only when an authentication error, like invalid username or password, occurs. For other types of errors, there will be a redirect to the `redirectUri`.
  */
 WebAuth.prototype.login = function (options, cb) {
   this.crossOriginAuthentication.login(options, cb);