diff --git a/docs/content/1.getting-started/3.quick-start.md b/docs/content/1.getting-started/3.quick-start.md index 91c210a6..6f6bc7ac 100644 --- a/docs/content/1.getting-started/3.quick-start.md +++ b/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: 'bernd@sidebase.io', - 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 + + + ``` -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: 'bernd@sidebase.io', - 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