docs: update local and refresh providers guide (#641)

docs/content/1.getting-started/3.quick-start.md

@@ -60,69 +60,149 @@ export default NuxtAuthHandler({
 
 ### Provider: `local`
 
-The local provider does not require any additional steps, as it relies on an already existing backend. By default, the `local` provider will try to reach this backend using the following default-configuration:
+The local provider does not require any additional steps, as it relies on an already existing backend. By default, the `local` provider will try to reach this backend using the following default-configuration. 
+
 ```ts
 {
+  auth: {
     baseURL: '/api/auth',
-    endpoints: {
+    provider: {
+      type: 'local',
+      endpoints: {
         signIn: { path: '/login', method: 'post' },
         signOut: { path: '/logout', method: 'post' },
         signUp: { path: '/register', method: 'post' },
         getSession: { path: '/session', method: 'get' }
+      },
+      token: { signInResponseTokenPointer: '/token/accessToken' },
     }
+  }
 }
 ```
 
-So when you call the `signIn` method, the endpoint `/api/auth/login` will be hit with the `username` and `password` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config).
-
-Note: The backend can also be in the same Nuxt 3 application, e.g., have a look at this example in the `nuxt-auth` repository:
-- [full nuxt app](https://github.com/sidebase/nuxt-auth/tree/main/playground-local)
-    - its [backend](https://github.com/sidebase/nuxt-auth/tree/main/playground-local/server/api/auth)
-    - its [`nuxt.config.ts`](https://github.com/sidebase/nuxt-auth/blob/main/playground-local/nuxt.config.ts)
+You can customize each endpoint to fit your needs or disable it by setting it to `false`. For example you may want to disable the `getSession` endpoint.
+```ts
+{
+  auth: {
+    baseURL: '/api/auth',
+    provider: {
+      type: 'local',
+      endpoints: {
+        getSession: false
+      }
+    }
+  }
+}
+```
 
 ::alert{type="info"}
-The linked example-implementation only serves as a starting-point and is not considered to be secure.
+See [configuration](/configuration/nuxt-config) for all options.
 ::
 
-The backend must accept a request with a body like:
-```ts
-{
-    username: '[email protected]',
-    password: 'hunter2'
-}
+
+#### Sign In Example
+
+To perform a sign in, all you need to do is calling the `signIn` function from `useAuth` composable and pass the credentials expected by your backend.
+
+::alert{type="warning"}
+Note that `signIn` method will be successful only if a valid token in the path specified by `auth.provider.token` in the config is returned in the API response. Otherwise it will throw an error. 
+::
+
+Take this example where we're using the default options and require the user to enter his email, phone, and password to login. 
+
+```vue
+<script setup>
+  const email = ref('')
+  const phone = ref('')
+  const password = ref('')
+
+  const { signIn } = useAuth()
+  async function signInWithCredentials() {
+    // Probably you'll do some validation here before submitting to the backend
+    // ...
+
+    // This is the object that our backend expects for the `signIn` endpoint
+    const credentials = {
+      email: email.value
+      phone: phone.value
+      password: password.value
+    }
+
+    try {
+      // This sends a POST request to the `auth.provider.endpoints.signIn` endpoint with `credentials` as the body
+      await signIn(credentials)
+      alert('Successfully logged in!')
+    } catch (error) {
+      console.error(error)
+    }
+  }
+</script>
+
+<template>
+  <div>
+    <h1>Enter your credentials to continue</h1>
+    <input v-model="email" type="email" />
+    <input v-model="phone" type="tel" />
+    <input v-model="password" type="password" />
+    <button @click="signInWithCredentials()" />
+  </div>
+</template>
 ```
 
-and return a token that can be used to authenticate future requests in the response body, e.g., like:
+If the backend response includes a token in the path `token.accessToken` (specified above in the config), the user will be signed successfully.
+
 ```ts
+// Backend response
 {
-    token: {
-        accessToken: 'eyBlaBlub'
-    }
+  token: {
+    accessToken: 'eyBlaBlub'
+  },
 }
 ```
 
+#### Full Example with `local` Provider
+
+Have a look at this example in the `nuxt-auth` repository which uses Nuxt in the backend too.
+- [full nuxt app](https://github.com/sidebase/nuxt-auth/tree/main/playground-local)
+    - its [backend](https://github.com/sidebase/nuxt-auth/tree/main/playground-local/server/api/auth)
+    - its [`nuxt.config.ts`](https://github.com/sidebase/nuxt-auth/blob/main/playground-local/nuxt.config.ts)
+
+::alert{type="info"}
+The linked example-implementation only serves as a starting-point and is not considered to be secure.
+::
+
 ### Provider: `refresh`
 ::alert{type="info"}
 The refresh provider is only available in version `0.6.3` and later
 ::
 
-The refresh provider does not require any additional steps, as it relies on an already existing backend. By default, the `refresh` provider will try to reach this backend using the following default-configuration:
+The refresh provider is exactly the same as the [local](#provider-local) provider except it has an additional `refresh` endpoint and a `refreshToken` object.
+
 ```ts
 {
+  auth: {
     baseURL: '/api/auth',
-    endpoints: {
+    provider: {
+      type: 'refresh',
+      endpoints: {
         signIn: { path: '/login', method: 'post' },
         signOut: { path: '/logout', method: 'post' },
         signUp: { path: '/register', method: 'post' },
-        getSession: { path: '/session', method: 'get' }
-        refresh: { path: '/refresh', method: 'post' },
+        getSession: { path: '/session', method: 'get' },
+        refresh: { path: '/refresh', method: 'post' }
+      },
+      token: { signInResponseTokenPointer: '/token' },
+      refreshToken: { signInResponseRefreshTokenPointer: '/refreshToken' },
     }
+  }
 }
 ```
 
-So when you call the `signIn` method, the endpoint `/api/auth/login` will be hit with the `username` and `password` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config).
+On a successful sign in with the default options, the value of `refreshToken` in the backend response will be saved and will be passed the body payload to the `/api/auth/refresh` endpoint when you call the `useAuth().refresh` method.
 
-Note: The backend can also be in the same Nuxt 3 application, e.g., have a look at this example in the `nuxt-auth` repository:
+#### Full Example with `refresh` Provider
+
+Have a look at this example in the `nuxt-auth` repository which uses Nuxt in the backend too.
 - [full nuxt app](https://github.com/sidebase/nuxt-auth/tree/main/playground-refresh)
     - its [backend](https://github.com/sidebase/nuxt-auth/tree/main/playground-refresh/server/api/auth)
     - its [`nuxt.config.ts`](https://github.com/sidebase/nuxt-auth/blob/main/playground-refresh/nuxt.config.ts)
@@ -131,25 +211,6 @@ Note: The backend can also be in the same Nuxt 3 application, e.g., have a look
 The linked example-implementation only serves as a starting-point and is not considered to be secure.
 ::
 
-The backend must accept a request with a body like:
-```ts
-{
-    username: '[email protected]',
-    password: 'hunter2'
-}
-```
-
-and return a token that can be used to authenticate future requests in the response body, e.g., like:
-```ts
-{
-    token: {
-        accessToken: 'eyBlaBlub'
-        refreshToken: 'eyBlaubwww'
-    }
-}
-```
-
-So when you call the `refresh` method, the endpoint `/api/auth/refresh` will be hit with the `refreshToken` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config).
 
 ## Finishing up