Movies
| Title | Director | Release Year | Genre | Rating |
|---|---|---|---|---|
| {movie.title} | {movie.director} | {movie.release_year} | {movie.genre} | {movie.rating} |
Loading...
if (error) return Error: {error}
return (
Movies
| Title | Director | Release Year | Genre | Rating |
|---|---|---|---|---|
| {movie.title} | {movie.director} | {movie.release_year} | {movie.genre} | {movie.rating} |
Loading...
{:else if error}
Error: {error}
{:else}
Movies
| Title | Director | Release Year | Genre | Rating |
|---|---|---|---|---|
| {movie.title} | {movie.director} | {movie.release_year} | {movie.genre} | {movie.rating} |
Loading...
Error: {{ error }}
Movies
| Title | Director | Release Year | Genre | Rating |
|---|---|---|---|---|
| {{ movie.title }} | {{ movie.director }} | {{ movie.release_year }} | {{ movie.genre }} | {{ movie.rating }} |
10
11
13
14
54
);
55
}
```
### Create a Simple Home Page
[Section titled “Create a Simple Home Page”](#create-a-simple-home-page)
Build a public homepage that adapts its content based on authentication status. This shows users different options depending on whether they’re signed in.
src/app/page.tsx
```tsx
1
import { createNhostClient } from "../lib/nhost/server";
2
3
export default async function Home() {
4
const nhost = await createNhostClient();
5
const session = nhost.getUserSession();
6
7
return (
8
Your Profile
12
15
44
45
User Information
16
17
43
18
Display Name:{" "}
19
{session?.user?.displayName || "Not set"}
20
21
22
Email: {session?.user?.email || "Not available"}
23
24
25
User ID: {session?.user?.id || "Not available"}
26
27
28
Roles: {session?.user?.roles?.join(", ") || "None"}
29
30
31
Email Verified:
32
39
{session?.user?.emailVerified ? "✓ Yes" : "✗ No"}
40
41
42
46
53
Session Information
47
48
52
49
{JSON.stringify(session, null, 2)}
50
51
9
10
12
13
{session ? (
14
23
);
24
}
```
### Create the Navigation Component
[Section titled “Create the Navigation Component”](#create-the-navigation-component)
Create a server-side navigation component that provides consistent navigation across all pages. This component adapts its links based on authentication status - showing different options for signed-in and signed-out users with server-side rendering.
src/components/Navigation.tsx
```tsx
1
import Link from "next/link";
2
import { createNhostClient } from "../lib/nhost/server";
3
4
export default async function Navigation() {
5
const nhost = await createNhostClient();
6
const session = nhost.getUserSession();
7
8
return (
9
34
);
35
}
```
### Update the Root Layout
[Section titled “Update the Root Layout”](#update-the-root-layout)
Configure the Next.js root layout to include the navigation and page content.
src/app/layout.tsx
```tsx
1
import type { Metadata } from "next";
2
import "./globals.css";
3
import Navigation from "../components/Navigation";
4
5
export const metadata: Metadata = {
6
title: "Nhost Next.js Tutorial",
7
description: "Next.js tutorial with Nhost authentication",
8
};
9
10
export default function RootLayout({
11
children,
12
}: {
13
children: React.ReactNode;
14
}) {
15
return (
16
17
18
Welcome to Nhost Next.js Demo
11
15
17
) : (
18
Hello, {session.user?.displayName || session.user?.email}!
16
19
21
)}
22
You are not signed in.
20{children}
20
21
22
);
23
}
```
### Add Application Styles
[Section titled “Add Application Styles”](#add-application-styles)
Replace the contents of the file `src/app/global.css` with the following styles to provide a clean and modern look for the application. This file will be used across the rest of series.
src/app/globals.css
```css
1
:root {
2
font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
3
line-height: 1.5;
4
font-weight: 400;
5
6
color-scheme: dark;
7
color: rgba(255, 255, 255, 0.87);
8
background-color: #242424;
9
10
font-synthesis: none;
11
text-rendering: optimizeLegibility;
12
-webkit-font-smoothing: antialiased;
13
-moz-osx-font-smoothing: grayscale;
14
}
15
16
body {
17
margin: 0;
18
min-width: 320px;
19
min-height: 100vh;
20
}
21
22
#root {
23
width: 100%;
24
min-height: 100vh;
25
display: block;
26
margin: 0;
27
padding: 0;
28
}
29
30
a {
31
font-weight: 500;
32
color: #646cff;
33
text-decoration: inherit;
34
}
35
36
a:hover {
37
color: #535bf2;
38
}
39
40
h1 {
41
font-size: 3.2em;
42
line-height: 1.1;
43
}
44
45
button {
46
border-radius: 8px;
47
border: 1px solid transparent;
48
padding: 0.6em 1.2em;
49
font-size: 1em;
50
font-weight: 500;
51
font-family: inherit;
52
background-color: #1a1a1a;
53
cursor: pointer;
54
transition: border-color 0.25s;
55
}
56
57
button:hover {
58
border-color: #646cff;
59
}
60
61
button:focus,
62
button:focus-visible {
63
outline: 4px auto -webkit-focus-ring-color;
64
}
65
66
input,
67
textarea {
68
width: 100%;
69
padding: 0.875rem 1rem;
70
border: 1px solid rgba(255, 255, 255, 0.2);
71
border-radius: 8px;
72
font-size: 0.875rem;
73
transition: all 0.2s ease;
74
background: rgba(255, 255, 255, 0.05);
75
color: white;
76
box-sizing: border-box;
77
font-family: inherit;
78
}
79
80
input:focus,
81
textarea:focus {
82
outline: none;
83
border-color: #3b82f6;
84
box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
85
background: rgba(255, 255, 255, 0.08);
86
}
87
88
input::placeholder,
89
textarea::placeholder {
90
color: rgba(255, 255, 255, 0.5);
91
}
92
93
textarea {
94
resize: vertical;
95
min-height: 4rem;
96
}
97
98
label {
99
display: block;
100
margin: 0 0 0.5rem 0;
101
font-weight: 500;
102
color: rgba(255, 255, 255, 0.9);
103
font-size: 0.875rem;
104
}
105
106
@keyframes spin {
107
0% {
108
transform: rotate(0deg);
109
}
110
100% {
111
transform: rotate(360deg);
112
}
113
}
114
115
/* Global Layout */
116
.app-content {
117
padding: 0 2rem 2rem;
118
max-width: 800px;
119
margin: 0 auto;
120
}
121
122
.page-center {
123
text-align: center;
124
padding: 2rem;
125
}
126
127
.page-header {
128
margin-bottom: 2rem;
129
}
130
131
.page-title {
132
font-weight: 700;
133
margin: 0;
134
display: flex;
135
align-items: center;
136
gap: 1rem;
137
}
138
139
.margin-bottom {
140
margin-bottom: 1rem;
141
}
142
143
.margin-top {
144
margin-top: 1rem;
145
}
146
147
.container {
148
width: 800px;
149
max-width: calc(100vw - 4rem);
150
min-width: 320px;
151
margin: 0 auto;
152
padding: 2rem;
153
box-sizing: border-box;
154
position: relative;
155
}
156
157
/* Status Messages */
158
.success-message {
159
padding: 1rem;
160
background-color: #d4edda;
161
color: #155724;
162
border-radius: 8px;
163
margin-bottom: 1rem;
164
}
165
166
.error-message {
167
background: rgba(239, 68, 68, 0.1);
168
color: #ef4444;
169
border: 1px solid rgba(239, 68, 68, 0.3);
170
border-radius: 12px;
171
padding: 1rem 1.5rem;
172
margin: 1rem 0;
173
}
174
175
.help-text {
176
color: #666;
177
}
178
179
.verification-status {
180
color: #28a745;
181
font-size: 1.2rem;
182
font-weight: bold;
183
margin-bottom: 1rem;
184
}
185
186
.verification-status.error {
187
color: #dc3545;
188
font-size: 1.1rem;
189
}
190
191
/* Email Verification Status */
192
.email-verified {
193
color: #10b981;
194
font-weight: bold;
195
margin-left: 0.5rem;
196
}
197
198
.email-unverified {
199
color: #ef4444;
200
font-weight: bold;
201
margin-left: 0.5rem;
202
}
203
204
/* Debug Info */
205
.debug-panel {
206
margin-bottom: 1rem;
207
padding: 1rem;
208
background-color: #f8f9fa;
209
border-radius: 8px;
210
text-align: left;
211
max-height: 200px;
212
overflow: auto;
213
}
214
215
.debug-title {
216
font-weight: bold;
217
margin-bottom: 0.5rem;
218
}
219
220
.debug-item {
221
margin-bottom: 0.25rem;
222
}
223
224
.debug-key {
225
font-family: monospace;
226
color: #007bff;
227
}
228
229
.debug-value {
230
font-family: monospace;
231
}
232
233
/* Session Display */
234
.session-display {
235
font-size: 0.75rem;
236
overflow: auto;
237
margin: 0;
238
line-height: 1.4;
239
white-space: pre-wrap;
240
word-break: break-word;
241
}
242
243
/* Loading Spinner */
244
.spinner-verify {
245
width: 32px;
246
height: 32px;
247
border: 3px solid #f3f3f3;
248
border-top: 3px solid #007bff;
249
border-radius: 50%;
250
animation: spin 1s linear infinite;
251
margin: 0 auto;
252
}
253
254
/* Navigation */
255
.navigation {
256
background: rgba(255, 255, 255, 0.05);
257
backdrop-filter: blur(10px);
258
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
259
position: sticky;
260
top: 0;
261
z-index: 100;
262
margin-bottom: 2rem;
263
}
264
265
.nav-container {
266
max-width: 800px;
267
margin: 0 auto;
268
padding: 1rem 2rem;
269
display: flex;
270
justify-content: space-between;
271
align-items: center;
272
}
273
274
.nav-logo {
275
font-size: 1.25rem;
276
font-weight: 700;
277
color: white;
278
text-decoration: none;
279
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
280
-webkit-background-clip: text;
281
-webkit-text-fill-color: transparent;
282
background-clip: text;
283
}
284
285
.nav-logo:hover {
286
opacity: 0.8;
287
}
288
289
.nav-links {
290
display: flex;
291
align-items: center;
292
gap: 1.5rem;
293
}
294
295
.nav-link {
296
color: rgba(255, 255, 255, 0.8);
297
text-decoration: none;
298
font-weight: 500;
299
font-size: 0.875rem;
300
padding: 0.5rem 0.75rem;
301
border-radius: 6px;
302
transition: all 0.2s ease;
303
border: none;
304
background: none;
305
cursor: pointer;
306
font-family: inherit;
307
}
308
309
.nav-link:hover {
310
color: white;
311
background: rgba(255, 255, 255, 0.1);
312
}
313
314
.nav-button {
315
color: #ef4444;
316
}
317
318
.nav-button:hover {
319
background: rgba(239, 68, 68, 0.2);
320
}
321
322
/* Buttons */
323
.btn {
324
padding: 0.75rem 1.5rem;
325
border: none;
326
border-radius: 8px;
327
font-weight: 500;
328
cursor: pointer;
329
transition: all 0.2s ease;
330
font-size: 0.875rem;
331
display: inline-flex;
332
align-items: center;
333
justify-content: center;
334
gap: 0.5rem;
335
min-width: 120px;
336
}
337
338
.btn-primary {
339
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
340
color: white;
341
}
342
343
.btn-primary:hover {
344
transform: translateY(-1px);
345
box-shadow: 0 4px 12px rgba(59, 130, 246, 0.4);
346
}
347
348
.btn-secondary {
349
background: rgba(255, 255, 255, 0.1);
350
color: white;
351
border: 1px solid rgba(255, 255, 255, 0.2);
352
}
353
354
.btn-secondary:hover {
355
background: rgba(255, 255, 255, 0.2);
356
}
357
358
.btn-cancel {
359
background: rgba(239, 68, 68, 0.1);
360
color: #ef4444;
361
border: 1px solid rgba(239, 68, 68, 0.3);
362
}
363
364
.btn-cancel:hover {
365
background: rgba(239, 68, 68, 0.2);
366
}
367
368
/* Loading State */
369
.loading-container {
370
display: flex;
371
justify-content: center;
372
align-items: center;
373
padding: 4rem 2rem;
374
}
375
376
.loading-content {
377
display: flex;
378
align-items: center;
379
gap: 1rem;
380
}
381
382
.spinner {
383
width: 2rem;
384
height: 2rem;
385
border: 3px solid rgba(59, 130, 246, 0.3);
386
border-top: 3px solid #3b82f6;
387
border-radius: 50%;
388
animation: spin 1s linear infinite;
389
}
390
391
.loading-text {
392
color: rgba(255, 255, 255, 0.7);
393
font-size: 0.875rem;
394
}
395
396
/* Empty State */
397
.empty-state {
398
text-align: center;
399
padding: 4rem 2rem;
400
background: rgba(255, 255, 255, 0.02);
401
border: 1px solid rgba(255, 255, 255, 0.1);
402
border-radius: 16px;
403
}
404
405
.empty-icon {
406
width: 4rem;
407
height: 4rem;
408
color: rgba(255, 255, 255, 0.4);
409
margin: 0 auto 1rem;
410
}
411
412
.empty-title {
413
font-size: 1.25rem;
414
font-weight: 600;
415
color: white;
416
margin: 0 0 0.5rem 0;
417
}
418
419
.empty-description {
420
color: rgba(255, 255, 255, 0.6);
421
margin: 0;
422
}
423
424
/* Forms */
425
.form-card {
426
background: rgba(255, 255, 255, 0.05);
427
backdrop-filter: blur(10px);
428
border: 1px solid rgba(255, 255, 255, 0.1);
429
border-radius: 16px;
430
padding: 2rem;
431
margin-bottom: 2rem;
432
width: 100%;
433
box-sizing: border-box;
434
}
435
436
.form-title {
437
font-size: 1.5rem;
438
font-weight: 600;
439
color: white;
440
margin: 0 0 1.5rem 0;
441
}
442
443
.form-fields {
444
display: flex;
445
flex-direction: column;
446
gap: 1.5rem;
447
}
448
449
.field-group {
450
display: flex;
451
flex-direction: column;
452
}
453
454
.form-actions {
455
display: flex;
456
gap: 1rem;
457
margin-top: 1rem;
458
}
459
460
/* Auth Pages */
461
.auth-form {
462
max-width: 400px;
463
}
464
465
.auth-form-field {
466
margin-bottom: 1rem;
467
}
468
469
.auth-input {
470
width: 100%;
471
padding: 0.5rem;
472
margin-top: 0.25rem;
473
}
474
475
.auth-error {
476
color: red;
477
margin-bottom: 1rem;
478
padding: 0.5rem;
479
background-color: #fee;
480
border-radius: 4px;
481
}
482
483
.auth-button {
484
width: 100%;
485
padding: 0.75rem;
486
color: white;
487
border: none;
488
border-radius: 4px;
489
cursor: pointer;
490
}
491
492
.auth-button:disabled {
493
cursor: not-allowed;
494
}
495
496
.auth-button.primary {
497
background-color: #28a745;
498
}
499
500
.auth-button.secondary {
501
background-color: #007bff;
502
}
503
504
.auth-links {
505
margin-top: 1rem;
506
}
507
508
/* Todos */
509
510
.todo-form {
511
width: 100%;
512
}
513
514
/* Todo List */
515
.todos-list {
516
display: flex;
517
flex-direction: column;
518
gap: 1rem;
519
}
520
521
.todo-card {
522
background: rgba(255, 255, 255, 0.03);
523
backdrop-filter: blur(10px);
524
border: 1px solid rgba(255, 255, 255, 0.1);
525
border-radius: 12px;
526
transition: all 0.2s ease;
527
overflow: hidden;
528
width: 100%;
529
box-sizing: border-box;
530
}
531
532
.todo-card:hover {
533
border-color: rgba(255, 255, 255, 0.2);
534
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
535
}
536
537
.todo-card.completed {
538
opacity: 0.7;
539
}
540
541
/* Todo Content */
542
.todo-content {
543
padding: 1rem 1.5rem;
544
}
545
546
.todo-edit {
547
padding: 1.5rem;
548
min-height: 200px;
549
}
550
551
.edit-fields {
552
display: flex;
553
flex-direction: column;
554
gap: 1rem;
555
}
556
557
.edit-actions {
558
display: flex;
559
gap: 1rem;
560
margin-top: 1.5rem;
561
}
562
563
.todo-header {
564
display: flex;
565
justify-content: space-between;
566
align-items: center;
567
gap: 1rem;
568
}
569
570
.todo-title-btn {
571
background: none;
572
border: none;
573
padding: 0;
574
text-align: left;
575
font-size: 1.25rem;
576
font-weight: 600;
577
color: white;
578
cursor: pointer;
579
transition: color 0.2s ease;
580
flex: 1;
581
line-height: 1.4;
582
word-wrap: break-word;
583
overflow-wrap: break-word;
584
max-width: calc(100% - 140px);
585
}
586
587
.todo-title-btn:hover {
588
color: #3b82f6;
589
}
590
591
.todo-title-btn.completed {
592
text-decoration: line-through;
593
color: rgba(255, 255, 255, 0.5);
594
}
595
596
.todo-actions {
597
display: flex;
598
gap: 0.5rem;
599
flex-shrink: 0;
600
min-width: 132px;
601
justify-content: flex-end;
602
}
603
604
/* Action Buttons */
605
.action-btn {
606
width: 40px;
607
height: 40px;
608
border: none;
609
border-radius: 6px;
610
cursor: pointer;
611
background: rgba(255, 255, 255, 0.05);
612
display: flex;
613
align-items: center;
614
justify-content: center;
615
font-size: 18px;
616
transition: all 0.2s ease;
617
-webkit-text-fill-color: currentColor;
618
}
619
620
.action-btn-complete {
621
color: #10b981;
622
font-size: 20px;
623
}
624
625
.action-btn-complete:hover {
626
background: rgba(16, 185, 129, 0.2);
627
color: #34d399;
628
}
629
630
.action-btn-edit {
631
color: #3b82f6;
632
}
633
634
.action-btn-edit:hover {
635
background: rgba(59, 130, 246, 0.2);
636
color: #60a5fa;
637
}
638
639
.action-btn-delete {
640
color: #ef4444;
641
}
642
643
.action-btn-delete:hover {
644
background: rgba(239, 68, 68, 0.2);
645
color: #f87171;
646
}
647
648
/* Add Todo Button */
649
.add-todo-btn {
650
width: 36px;
651
height: 36px;
652
border: none;
653
border-radius: 6px;
654
cursor: pointer;
655
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
656
display: flex;
657
align-items: center;
658
justify-content: center;
659
color: white;
660
font-size: 18px;
661
font-weight: normal;
662
-webkit-text-fill-color: white;
663
transition: all 0.2s ease;
664
}
665
666
.add-todo-btn:hover {
667
transform: scale(1.1);
668
box-shadow: 0 4px 20px rgba(59, 130, 246, 0.4);
669
}
670
671
/* Todo Details */
672
.todo-details {
673
margin-top: 1rem;
674
padding-top: 1rem;
675
border-top: 1px solid rgba(255, 255, 255, 0.1);
676
}
677
678
.description {
679
background: rgba(255, 255, 255, 0.02);
680
border: 1px solid rgba(255, 255, 255, 0.1);
681
border-radius: 8px;
682
padding: 1rem;
683
margin-bottom: 1rem;
684
}
685
686
.description p {
687
margin: 0;
688
color: rgba(255, 255, 255, 0.8);
689
line-height: 1.6;
690
}
691
692
.description.completed p {
693
text-decoration: line-through;
694
color: rgba(255, 255, 255, 0.5);
695
}
696
697
.todo-meta {
698
display: flex;
699
justify-content: space-between;
700
align-items: center;
701
gap: 1rem;
702
}
703
704
.meta-dates {
705
display: flex;
706
gap: 1rem;
707
flex-wrap: wrap;
708
}
709
710
.meta-item {
711
font-size: 0.75rem;
712
color: rgba(255, 255, 255, 0.5);
713
}
714
715
.completion-badge {
716
display: flex;
717
align-items: center;
718
gap: 0.25rem;
719
font-size: 0.75rem;
720
color: #10b981;
721
font-weight: 500;
722
}
723
724
.completion-icon {
725
width: 0.875rem;
726
height: 0.875rem;
727
}
728
729
/* Responsive Design */
730
@media (max-width: 768px) {
731
.nav-container {
732
padding: 1rem;
733
flex-direction: column;
734
gap: 1rem;
735
}
736
737
.nav-links {
738
gap: 1rem;
739
flex-wrap: wrap;
740
justify-content: center;
741
}
742
743
.container {
744
padding: 1rem;
745
}
746
747
.form-actions {
748
flex-direction: column;
749
}
750
751
.edit-actions {
752
flex-direction: column;
753
}
754
755
.todo-header {
756
flex-direction: column;
757
align-items: flex-start;
758
gap: 1rem;
759
}
760
761
.todo-actions {
762
align-self: stretch;
763
justify-content: center;
764
}
765
766
.meta-dates {
767
flex-direction: column;
768
gap: 0.25rem;
769
}
770
771
.todo-meta {
772
flex-direction: column;
773
align-items: flex-start;
774
gap: 0.5rem;
775
}
776
}
777
778
/* File Upload */
779
.file-upload-btn {
780
min-height: 120px;
781
flex-direction: column;
782
gap: 0.5rem;
783
width: 100%;
784
border: 2px dashed rgba(255, 255, 255, 0.3);
785
display: flex;
786
align-items: center;
787
justify-content: center;
788
cursor: pointer;
789
transition: all 0.2s ease;
790
}
791
792
.file-upload-btn:hover {
793
border-color: rgba(255, 255, 255, 0.5);
794
background-color: rgba(255, 255, 255, 0.05);
795
}
796
797
.file-upload-info {
798
margin-top: 0.5rem;
799
font-size: 0.875rem;
800
color: rgba(255, 255, 255, 0.8);
801
}
802
803
/* File Table */
804
.file-table {
805
width: 100%;
806
border-collapse: collapse;
807
}
808
809
.file-table th {
810
padding: 0.75rem;
811
text-align: left;
812
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
813
color: rgba(255, 255, 255, 0.7);
814
font-weight: 500;
815
font-size: 0.875rem;
816
}
817
818
.file-table th:last-child {
819
text-align: center;
820
}
821
822
.file-table td {
823
padding: 0.75rem;
824
border-bottom: 1px solid rgba(255, 255, 255, 0.05);
825
}
826
827
.file-table tr:hover {
828
background-color: rgba(255, 255, 255, 0.02);
829
}
830
831
.file-name {
832
color: white;
833
font-weight: 500;
834
}
835
836
.file-meta {
837
color: rgba(255, 255, 255, 0.6);
838
font-size: 0.875rem;
839
}
840
841
.file-actions {
842
display: flex;
843
gap: 0.5rem;
844
justify-content: center;
845
}
846
847
/* Responsive File Table */
848
@media (max-width: 768px) {
849
.file-table {
850
font-size: 0.875rem;
851
}
852
853
.file-table th,
854
.file-table td {
855
padding: 0.5rem;
856
}
857
858
.file-actions {
859
flex-direction: column;
860
gap: 0.25rem;
861
}
862
}
```
### Run and test the Application
[Section titled “Run and test the Application”](#run-and-test-the-application)
Start the development server to test your route protection implementation:
```bash
npm run dev
```
Things to try out:
1. Try navigating to `/profile` - you should be redirected to the homepage `/` since you’re not authenticated.
2. Because you are not signed in, the navigation bar should only show the “Home” link and the placeholder for signin/signup links.
3. On the homepage, you should see a message indicating that you are not signed in.
After we complete the next tutorial on user authentication, you will be able to sign in and access the protected `/profile` page and see how the navigation bar and homepage updates accordingly.
## How It Works
[Section titled “How It Works”](#how-it-works)
1. **Server-Side Helpers**: Utilities for handling authentication in Next.js server components and proxy
2. **Proxy Route Protection**: Next.js proxy runs before any page renders, automatically redirecting unauthenticated users from protected routes and refreshing tokens
3. **Protected Pages**: Server components can assume authentication since the proxy handles protection, focusing purely on rendering authenticated content
4. **Navigation**: Server-side navigation component that adapts its links based on authentication status
5. **Automatic Redirects**: All route protection and redirects are handled at the proxy level for optimal performance and security
## Key Features Demonstrated
[Section titled “Key Features Demonstrated”](#key-features-demonstrated)
Proxy Route Protection
Routes are protected at the proxy level, running before any page renders to provide the highest level of security and performance by preventing unauthorized access before components load.
No Loading States
Server-side authentication checks eliminate the need for loading spinners during authentication verification, providing instant feedback to users.
Automatic Server Redirects
Users are automatically redirected based on their authentication status using Next.js proxy redirects, ensuring proper navigation flow before any client-side rendering.
Cross-tab Synchronization
Authentication state is synchronized across multiple browser tabs using Nhost’s session storage events with Next.js router refresh for server-side state updates.
Cookie-Based Session Management
Complete user session and profile information is shared between server and client using cookie-based storage, enabling seamless SSR and client-side functionality.
Server-Side Rendering
Authentication-dependent content is rendered server-side for improved SEO, performance, and security compared to client-only approaches.
Automatic Token Refresh
The proxy automatically refreshes authentication tokens before they expire, ensuring seamless user experience without manual token management.
# User Authentication in Next.js
> Add sign up, sign in, and email verification to your Next.js App Router app using Nhost Auth and session-aware server components.
This tutorial part builds upon the [Protected Routes part](/getting-started/tutorials/nextjs/2-protected-routes) by adding complete email/password authentication with email verification functionality. You’ll implement sign up, sign in, email verification, and sign out features to create a full authentication flow.
Note
This is **Part 3** in the Full-Stack Next.js Development with Nhost series. This part creates a production-ready authentication system with secure email verification and proper error handling using Next.js App Router.
## Full-Stack Next.js Development with Nhost
[Section titled “Full-Stack Next.js Development with Nhost”](#full-stack-nextjs-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/nextjs/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/nextjs/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/nextjs/2-protected-routes)
[Route protection basics](/getting-started/tutorials/nextjs/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/nextjs/3-user-authentication)
[**Current** - Complete auth flow](/getting-started/tutorials/nextjs/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/nextjs/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/nextjs/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/nextjs/5-file-uploads)
[File upload and management](/getting-started/tutorials/nextjs/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [Protected Routes part](/getting-started/tutorials/nextjs/2-protected-routes) first
* The project from the previous part set up and running
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create the Sign In Flow
[Section titled “Create the Sign In Flow”](#create-the-sign-in-flow)
In this step, we’ll create a complete sign-in flow using Next.js App Router patterns. We’ll build three key files: a server component for the main page that handles URL parameters, a client component for the interactive form, and server actions for secure authentication processing.
* Page Component
The main sign-in page is a **server component** that handles URL parameters (like error messages) and renders the sign-in form. This component runs on the server and can access search parameters directly.
src/app/signin/page.tsx
```tsx
1
import Link from "next/link";
2
import SignInForm from "./SignInForm";
3
4
export default async function SignIn({
5
searchParams,
6
}: {
7
searchParams: Promise<{ error?: string }>;
8
}) {
9
// Extract error from URL parameters
10
const params = await searchParams;
11
const error = params?.error;
12
13
return (
14
15
24
);
25
}
```
* Form Component
The sign-in form is a **client component** that handles user interactions, loading states, and form submissions. It communicates with server actions and provides real-time feedback to users.
src/app/signin/SignInForm.tsx
```tsx
1
"use client";
2
3
import { useRouter } from "next/navigation";
4
import { useId, useState } from "react";
5
import { signIn } from "./actions";
6
7
interface SignInFormProps {
8
initialError?: string;
9
}
10
11
export default function SignInForm({ initialError }: SignInFormProps) {
12
const [error, setError] = useStateSign In
16
19
23
20 Don't have an account? Sign Up 21
22
22
36
);
37
}
38
39
return (
40
Check Your Email
23
24
32
25 We've sent a verification link to {email} 26
2728 Please check your email and click the verification link to activate 29 your account. 30
3133 Back to Sign In 34
35
41
50
);
51
}
```
* Form Component
The registration form is a **client component** that collects user information (display name, email, password) and handles form validation, loading states, and error feedback during the sign-up process.
src/app/signup/SignUpForm.tsx
```tsx
1
"use client";
2
3
import { generatePKCEPair } from "@nhost/nhost-js/auth";
4
import { useRouter } from "next/navigation";
5
import { useId, useState } from "react";
6
import { signUp } from "./actions";
7
8
interface SignUpFormProps {
9
initialError?: string;
10
}
11
12
export default function SignUpForm({ initialError }: SignUpFormProps) {
13
const [error, setError] = useStateSign Up
42
45
49
46 Already have an account? Sign In 47
48
16
39
);
40
}
```
Caution
**Important Configuration Required:** Before testing email verification, you must configure your Nhost project’s authentication settings:
1. Go to your Nhost project dashboard
2. Navigate to **Auth → Settings → Authentication**
3. Add your local development URL (e.g., `http://localhost:3000`) to the **Allowed Redirect URLs** field
4. Ensure your production domain is also added when deploying
Without this configuration, you’ll receive a `redirectTo not allowed` error when users attempt to sign up or verify their email addresses.
### Create the Sign Out System
[Section titled “Create the Sign Out System”](#create-the-sign-out-system)
In this step, we’ll implement user sign-out functionality using Next.js patterns. We’ll create a client component for the sign-out button and a server action to handle the actual sign-out process securely on the server side.
* Sign Out Button
The sign-out button is a **client component** that provides an interactive button for users to sign out. It handles the user interaction and calls the server action, then manages navigation and component refresh after sign-out.
src/components/SignOutButton.tsx
```tsx
1
"use client";
2
3
import { useRouter } from "next/navigation";
4
import { signOut } from "../lib/nhost/actions";
5
6
export default function SignOutButton() {
7
const router = useRouter();
8
9
const handleSignOut = async () => {
10
try {
11
await signOut();
12
router.push("/");
13
router.refresh(); // Refresh to update server components
14
} catch (err) {
15
console.error("Error signing out:", err);
16
}
17
};
18
19
return (
20
27
);
28
}
```
* Server Action
The sign-out server action handles the authentication logic securely on the server side. It retrieves the current session, calls Nhost’s sign-out method with the refresh token, and redirects the user to the home page after successful sign-out.
src/lib/nhost/actions.ts
```tsx
1
"use server";
2
3
import { redirect } from "next/navigation";
4
import { createNhostClient } from "./server";
5
6
export async function signOut() {
7
try {
8
const nhost = await createNhostClient();
9
const session = nhost.getUserSession();
10
11
if (session) {
12
await nhost.auth.signOut({
13
refreshToken: session.refreshToken,
14
});
15
}
16
} catch (err) {
17
console.error("Error signing out:", err);
18
throw err;
19
}
20
21
redirect("/");
22
}
```
### Update Navigation Component
[Section titled “Update Navigation Component”](#update-navigation-component)
In this step, we’ll update the server-side navigation component that shows different links based on the user’s authentication state. The navigation will display “Sign In” and “Sign Up” links for unauthenticated users, and “Profile” and “Sign Out” for authenticated users.
src/components/Navigation.tsx
```tsx
1
import Link from "next/link";
2
import { createNhostClient } from "../lib/nhost/server";
3
import SignOutButton from "./SignOutButton";
4
5
export default async function Navigation() {
6
const nhost = await createNhostClient();
7
const session = nhost.getUserSession();
8
9
return (
10
41
);
42
}
```
### Update Public Routes in Proxy
[Section titled “Update Public Routes in Proxy”](#update-public-routes-in-proxy)
In this step, we’ll configure the proxy to allow access to authentication-related routes without requiring authentication. This ensures that users can access sign-in, sign-up, and email verification pages even when not logged in.
src/proxy.ts
```tsx
1
import type { NextRequest } from "next/server";
2
import { NextResponse } from "next/server";
3
import { handleNhostProxy } from "./lib/nhost/server";
4
5
// Define public routes that don't require authentication
6
const publicRoutes = ["/", "/signin", "/signup", "/verify", "/verify/error"];
7
8
export async function proxy(request: NextRequest) {
9
// Create a response that we'll modify as needed
10
const response = NextResponse.next();
11
12
// Get the current path
13
const path = request.nextUrl.pathname;
14
15
// Check if this is a public route or a public asset
16
const isPublicRoute = publicRoutes.some(
17
(route) => path === route || path.startsWith(`${route}/`),
18
);
19
20
// Handle Nhost authentication and token refresh
21
// Always call this to ensure session is up-to-date
22
// even for public routes, so that session changes are detected
23
const session = await handleNhostProxy(request, response);
24
25
// If it's a public route, allow access without checking auth
26
if (isPublicRoute) {
27
return response;
28
}
29
30
// If no session and not a public route, redirect to signin
31
if (!session) {
32
const homeUrl = new URL("/", request.url);
33
return NextResponse.redirect(homeUrl);
34
}
35
36
// Session exists, allow access to protected route
37
return response;
38
}
39
40
// Define which routes this proxy should run on
41
export const config = {
42
matcher: [
43
/*
44
* Match all request paths except:
45
* - _next/static (static files)
46
* - _next/image (image optimization files)
47
* - favicon.ico (favicon file)
48
* - public files (public directory)
49
*/
50
"/((?!_next/static|_next/image|favicon.ico|public).*)",
51
],
52
};
```
### Run and Test the Application
[Section titled “Run and Test the Application”](#run-and-test-the-application)
Start your Next.js development server and test the complete authentication flow to ensure everything works properly.
```bash
npm run dev
```
Things to try out:
1. **Email Verification Flow**: Try signing up with a new email address. Check your email for the verification link and click it. The verification page will exchange the authorization code for a session using PKCE and redirect you to your profile.
2. **Sign In/Out Flow**: Try signing out and then signing back in with the same credentials using the server actions.
3. **Server-Side Navigation**: Notice how navigation links change based on authentication state - the navigation component is rendered server-side and shows different content based on the session.
4. **Route Protection**: Try accessing protected routes while logged out to see the proxy-based protection in action.
5. **Cross-Tab Consistency**: Open multiple tabs and test signing out from one tab. Unlike client-side React apps, you’ll need to refresh or navigate to see changes in other tabs due to server-side rendering.
## Key Features Demonstrated
[Section titled “Key Features Demonstrated”](#key-features-demonstrated)
Server Components & Actions
Full authentication flow using Next.js App Router with server components and server actions for secure, server-side processing.
PKCE Verification
Server-side `/verify` page that exchanges authorization codes for sessions using PKCE, with the verifier stored in a cookie and the token exchange performed entirely on the server.
Client/Server Separation
Clear separation between server components for rendering and client components for interactivity, following Next.js best practices.
Error Handling
Comprehensive error handling with URL-based error states and dedicated error pages for different failure scenarios.
Session Management
Server-side session handling with sign out functionality using server actions and proper state management.
# GraphQL Operations in Next.js
> Learn how to perform GraphQL operations and manage database permissions while building a complete todos application with Nhost and Next.js
This part builds upon the previous parts by demonstrating how to perform GraphQL operations with proper [database permissions](/products/graphql/permissions) using Next.js App Router patterns. You’ll learn how to design database tables, configure user permissions, and implement complete CRUD operations through GraphQL queries and mutations using server components, client components, and server actions.
Note
This is **Part 4** in the Full-Stack Next.js Development with Nhost series. This part focuses on GraphQL operations, database management, and permission-based data access control using Next.js App Router with server/client component separation.
## Full-Stack Next.js Development with Nhost
[Section titled “Full-Stack Next.js Development with Nhost”](#full-stack-nextjs-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/nextjs/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/nextjs/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/nextjs/2-protected-routes)
[Route protection basics](/getting-started/tutorials/nextjs/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/nextjs/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/nextjs/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/nextjs/4-graphql-operations)
[**Current** - CRUD operations with GraphQL](/getting-started/tutorials/nextjs/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/nextjs/5-file-uploads)
[File upload and management](/getting-started/tutorials/nextjs/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [User Authentication part](/getting-started/tutorials/nextjs/3-user-authentication) first
* The project from the previous part set up and running
## What You’ll Build
[Section titled “What You’ll Build”](#what-youll-build)
By the end of this part, you’ll have:
* **GraphQL queries and mutations** for complete CRUD operations
* **Database schema** with proper relationships and constraints
* **User permissions** for secure data access control
* **Next.js components** using server/client patterns that interact with GraphQL endpoint
* **Server actions** for secure data mutations
* **Server components** for efficient data fetching
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create the To-Dos Table
[Section titled “Create the To-Dos Table”](#create-the-to-dos-table)
First, we’ll perform the database changes to set up the todos table with proper schema and relationships to users.
In your Nhost project dashboard:
1. Navigate to **Database**
2. Click on **SQL Console**
Enter the following SQL:
* SQL
```sql
CREATE TABLE public.todos (
id uuid DEFAULT gen_random_uuid() NOT NULL,
created_at timestamptz DEFAULT now() NOT NULL,
updated_at timestamptz DEFAULT now() NOT NULL,
title text NOT NULL,
details text,
completed bool DEFAULT false NOT NULL,
user_id uuid NOT NULL,
PRIMARY KEY (id),
FOREIGN KEY (user_id) REFERENCES auth.users (id) ON UPDATE CASCADE ON DELETE CASCADE
);
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = now();
RETURN NEW;
END;
$$ language 'plpgsql';
CREATE TRIGGER update_todos_updated_at
BEFORE UPDATE ON public.todos
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();
```
* UI
Caution
Please make sure to enable **Track this** so that the new table todos is available through the auto-generated APIs
### Set Up Permissions
[Section titled “Set Up Permissions”](#set-up-permissions)
It’s now time to set permission rules for the table you just created. With the table `todos` selected, click on **…**, followed by **Edit Permissions**. You will set permissions for the **user** role and actions **insert**, **select**, **update**, and **delete**.
* Insert
When inserting permissions we are only allowing users to set the `title`, `details`, and `completed` columns as the rest of the columns are set automatically by the backend. The `user_id` column is configured as a preset to the currently authenticated user’s ID using the `X-Hasura-User-Id` session variable. This ensures that each todo is associated with the user who created it.
* Select
For selecting (reading) todos, we are allowing to read all columns but only for rows where the `user_id` matches the authenticated user’s ID. This ensures that users can only see their own todos.
* Update
When updating todos, we are allowing users to modify the `title`, `details`, and `completed` columns but only for rows where the `user_id` matches their own ID. This prevents users from modifying todos that do not belong to them.
* Delete
For deleting todos, we are allowing users to delete rows only where the `user_id` matches their own ID. This ensures that users cannot delete todos that belong to other users.
### Create the Todos Page System
[Section titled “Create the Todos Page System”](#create-the-todos-page-system)
Now let’s implement the Next.js page system that uses the database we just configured. We’ll create a server component for the main page, a client component for the interactive todos interface, and server actions for secure data mutations.
* Page Component
The main todos page is a **server component** that fetches initial data server-side and renders the todos interface. This component runs on the server and provides the initial state to the client component.
src/app/todos/page.tsx
```tsx
1
import { createNhostClient } from "../../lib/nhost/server";
2
import TodosClient from "./TodosClient";
3
4
// The interfaces below define the structure of our data
5
// They are not strictly necessary but help with type safety
6
7
// Represents a single todo item
8
export interface Todo {
9
id: string;
10
title: string;
11
details: string | null;
12
completed: boolean;
13
created_at: string;
14
updated_at: string;
15
user_id: string;
16
}
17
18
// This matches the GraphQL response structure for fetching todos
19
// Can be used as a generic type on the request method
20
interface GetTodos {
21
todos: Todo[];
22
}
23
24
export default async function TodosPage() {
25
// Fetch initial todos data server-side
26
const nhost = await createNhostClient();
27
const session = nhost.getUserSession();
28
29
let initialTodos: Todo[] = [];
30
let error: string | null = null;
31
32
if (session) {
33
try {
34
// Make GraphQL request to fetch todos using Nhost server client
35
// The query automatically filters by user_id due to permissions
36
const response = await nhost.graphql.requestEmail Verification
17 18
19
38
Verification failed
20{message}
21 22 {urlParams.length > 0 && ( 23
24
32
)}
33
34
35
Back to Sign In
36
37
URL Parameters:
25 {urlParams.map(([key, value]) => ( 26
27
{key}:{" "}
28
{value}
29
30
))}
31
120
121
135
136
{error && (
137
478
{/if}
```
### Update Navigation Links
[Section titled “Update Navigation Links”](#update-navigation-links)
Add a link to the todos page in the navigation layout. Update your `src/routes/+layout.svelte` file to include the todos link:
src/routes/+layout.svelte
```svelte
1
29
30
122 My Todos 123 {!showAddForm && ( 124 132 )} 133
134
138
Error: {error}
139
140
)}
141
142
{showAddForm && (
143
144
316
317
{/if}
318
319
{#if !showAddForm}
320
{#if loading}
321
322
327
{:else}
328
323
324
Loading todos...
325
326
329
{#if todos.length === 0}
330
475
{/if}
476
{/if}
477
331
345
350
{:else}
351
{#each todos as todo (todo.id)}
352
No todos yet
346347 Create your first todo to get started! 348
349
353
{#if editingTodo?.id === todo.id}
354
472
{/each}
473
{/if}
474
355
390
{:else}
391
356
389
357
358
363
364
365
366
371
372
373
380
387
388
392
470
{/if}
471
393
400
429
430
{#if expandedTodos.has(todo.id)}
431
401
411
419
427
428
432
{#if todo.details}
433
468
{/if}
469
434
436
{/if}
437
438
467
{todo.details}
435
31
58
59
```
### Test Your Complete Application
[Section titled “Test Your Complete Application”](#test-your-complete-application)
Run your SvelteKit application and test all the functionality:
```bash
npm run dev
```
Things to try out:
1. Try signing in and out and see how the Todos page is only available when authenticated
2. Create, view, edit, complete, and delete todos. See how the UI updates accordingly
3. Open the application in another browser or incognito window, sign in with a different account and verify that you cannot see or modify todos from the first account
## Key Features Implemented
[Section titled “Key Features Implemented”](#key-features-implemented)
Database Schema
Properly designed todos table with constraints, indexes, and automatic timestamp updates for optimal performance.
GraphQL API
Auto-generated GraphQL API with queries and mutations for full CRUD operations on todos.
Row-Level Security
Comprehensive permissions ensuring users can only access their own todos through all GraphQL operations.
CRUD Operations
Complete Create, Read, Update, Delete functionality with proper error handling and user feedback.
Rich Interface
Expandable todo items, inline editing, completion status, and detailed timestamps using SvelteKit’s reactive UI patterns.
# File Uploads in SvelteKit
> Add file uploads to your SvelteKit app with Nhost Storage: configure buckets and permissions and build a file management system.
This part builds upon the previous GraphQL operations part by demonstrating how to implement [file upload functionality](/products/storage) with proper storage permissions. You’ll learn how to create [storage buckets](/products/storage/buckets), configure upload permissions, and implement complete file management operations in a SvelteKit application.
Note
This is **Part 5** in the Full-Stack SvelteKit Development with Nhost series. This part focuses on file storage, upload operations, and permission-based file access control in a production application.
## Full-Stack SvelteKit Development with Nhost
[Section titled “Full-Stack SvelteKit Development with Nhost”](#full-stack-sveltekit-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/svelte/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/svelte/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/svelte/2-protected-routes)
[Route protection basics](/getting-started/tutorials/svelte/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/svelte/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/svelte/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/svelte/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/svelte/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/svelte/5-file-uploads)
[**Current** - File upload and management](/getting-started/tutorials/svelte/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [GraphQL Operations part](/getting-started/tutorials/svelte/4-graphql-operations) first
* The project from the previous part set up and running
## What You’ll Build
[Section titled “What You’ll Build”](#what-youll-build)
By the end of this part, you’ll have:
* A **personal bucket** so users can upload their own private files
* **File upload functionality**
* **File management interface** for viewing and deleting files
* **Security permissions** ensuring users can only access their own files
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create a Personal Storage Bucket
[Section titled “Create a Personal Storage Bucket”](#create-a-personal-storage-bucket)
First, we’ll create a storage bucket where users can upload their personal files.
In your Nhost project dashboard:
1. Navigate to **Storage**
2. Click **New Bucket** in the sidebar
3. Set the name to `personal` and click **Save**
### Configure Storage Permissions
[Section titled “Configure Storage Permissions”](#configure-storage-permissions)
Now we need to set up permissions for the storage bucket to ensure the `user` role can only upload, view, and delete their own files.
In the dashboard, navigate to **Storage** and click **Permissions** to open the permission grid.
* Upload
Click the **Upload** cell for the `user` role.
1. Select **With custom check** and add a rule: `bucket_id` equals `personal`
2. Enable the **Uploader identity** toggle — this automatically sets `uploaded_by_user_id` to the current user’s ID on every upload, so you can reference it in Download and Delete rules.
* Download
Click the **Download** cell for the `user` role.
1. Select **With custom check** and add two rules combined with AND:
* `bucket_id` equals `personal`
* `uploaded_by_user_id` equals `X-Hasura-User-Id`
* Delete
Click the **Delete** cell for the `user` role.
1. Select **With custom check** and add the same two rules as Download:
* `bucket_id` equals `personal`
* `uploaded_by_user_id` equals `X-Hasura-User-Id`
Note
You can read more about storage permissions [here](/products/storage/permissions)
### Create the File Upload Component
[Section titled “Create the File Upload Component”](#create-the-file-upload-component)
Now let’s implement the SvelteKit page component for file upload functionality.
src/routes/files/+page.svelte
```svelte
1
244
245
{#if !$auth.session}
246
249
{:else}
250
60
{#if children}
61
{@render children()}
62
{/if}
63
64
251
252
254
255
403
{/if}
```
### Update Navigation Links
[Section titled “Update Navigation Links”](#update-navigation-links)
Add a link to the files page in the navigation layout. Update your `src/routes/+layout.svelte` file to include the files link:
src/routes/+layout.svelte
```svelte
1
29
30
File Upload
253
256
315
316
Upload a File
257 258
259
267
295
296
297
{#if error}
298
299
{/if}
300
301
{#if uploadResult}
302
303
{/if}
304
305
314
317
402
Your Files
318 319 {#if deleteStatus} 320
321
{deleteStatus.message}
322
323
{/if}
324
325
{#if isFetching}
326
327
332
{:else if files.length === 0}
333
328
329
Loading files...
330
331
334
348
351
{:else}
352
No files yet
349Upload your first file to get started!
350
353
354
355
399
400
{/if}
401
| Name | 357Type | 358Size | 359Actions | 360
|---|---|---|---|
| {file.name} | 366{file.mimeType} | 367{formatFileSize(file.size || 0)} | 368
369
370
384
393
394
|
395
31
59
60
```
### Test Your File Upload System
[Section titled “Test Your File Upload System”](#test-your-file-upload-system)
Run your SvelteKit application and test all the functionality:
```bash
npm run dev
```
Things to try out:
1. Try signing in and out and see how the file upload page is only accessible when signed in.
2. Upload different types of files (images, documents, etc.)
3. View and delete files
4. Sign in with another account and verify you cannot see files from the first account
## Key Features Implemented
[Section titled “Key Features Implemented”](#key-features-implemented)
Storage Bucket
Dedicated personal storage bucket with proper configuration for user file isolation.
File Upload Interface
User-friendly upload interface with file selection, preview, and progress feedback using SvelteKit’s reactive patterns.
File Management
Complete file listing with metadata, viewing capabilities, and deletion functionality.
File Type Handling
Intelligent handling of different file types with appropriate viewing/download behavior.
Error Handling
Comprehensive error handling with user-friendly messages for upload and management operations using Svelte stores.
# Create Your Nhost Project for Vue
> Create and configure a new Nhost project as the backend for your Vue app, with PostgreSQL, GraphQL, auth, and storage ready to use.
Welcome to the **Full-Stack Vue Development with Nhost** series! In this comprehensive tutorial series, you’ll build a complete Vue application with Nhost that demonstrates authentication, database operations, and file management.
## About This Tutorial Series
[Section titled “About This Tutorial Series”](#about-this-tutorial-series)
This tutorial series is divided into **5 parts**, each focusing on a specific aspect of building modern web applications with Nhost and Vue. By the end of the series, you’ll have built a fully functional application featuring:
* **User Authentication** - Complete sign up, sign in, and email verification flow
* **Todo Management** - Users can create, update, delete, and mark todos as complete
* **File Uploads** - Users can upload and manage files with proper permissions
* **Protected Routes** - Secure areas that only authenticated users can access
Note
This is **Part 1** in the Full-Stack Vue Development with Nhost series. This part sets up the foundation by creating your Nhost project and understanding the series structure.
## Full-Stack Vue Development with Nhost
[Section titled “Full-Stack Vue Development with Nhost”](#full-stack-vue-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/vue/1-introduction)
[**Current** - Set up your Nhost project](/getting-started/tutorials/vue/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/vue/2-protected-routes)
[Route protection basics](/getting-started/tutorials/vue/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/vue/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/vue/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/vue/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/vue/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/vue/5-file-uploads)
[File upload and management](/getting-started/tutorials/vue/5-file-uploads)
## What You’ll Learn
[Section titled “What You’ll Learn”](#what-youll-learn)
Throughout this series, you’ll master:
* Setting up and configuring Nhost projects
* Implementing secure authentication flows
* Building protected routes with Vue Router
* Performing GraphQL queries and mutations
* Managing file uploads and storage
* Configuring database permissions and security
* Building responsive Vue interfaces
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Node.js 22+ installed on your machine
* Basic knowledge of Vue and JavaScript
* Understanding of modern web development concepts
Creating an Nhost project is the first step to building your application with Nhost. Let’s get started by setting up your backend infrastructure.
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Sign Up or Log in
[Section titled “Sign Up or Log in”](#sign-up-or-log-in)
If you don’t have an Nhost account, sign up at [Nhost](https://app.nhost.io/). If you already have an account, log in.
### Create a New Project
[Section titled “Create a New Project”](#create-a-new-project)
Click on the “Create Project” button on your dashboard or follow the onboarding prompts if you’re a new user.
### Take note of your project subdomain and region
[Section titled “Take note of your project subdomain and region”](#take-note-of-your-project-subdomain-and-region)
Take note of your project subdomain and region. You will need this information to connect your application to the Nhost backend in upcoming tutorials.
## What’s Next?
[Section titled “What’s Next?”](#whats-next)
With your Nhost project created, you now have access to:
* [**PostgreSQL Database**](/products/database) - For storing your application data
* [**Authentication Service**](/products/auth) - For managing users and sessions
* [**GraphQL API**](/products/graphql) - For querying and mutating data
* [**File Storage**](/products/storage) - For uploading and managing files
* [**Functions**](/products/functions) - For running serverless functions
In the [next tutorial](/getting-started/tutorials/vue/2-protected-routes), you’ll start building your Vue application and learn how to protect routes based on user authentication status.
Tip
Keep your project subdomain and region handy - you’ll need them throughout the series to connect your Vue application to the Nhost backend.
# Protecting Routes and Content in Vue
> Learn how to protect routes and content in a Vue application using Nhost authentication.
This tutorial part demonstrates how to implement robust route protection in a Vue application using [Nhost authentication](/products/auth). You’ll build a complete authentication system with a protected `/profile` page that includes cross-tab session synchronization and automatic redirects. In addition, we will see how to show conditional navigation and content based on authentication status.
Note
This is **Part 2** in the Full-Stack Vue Development with Nhost series. This part builds a foundation for authentication-protected routes that you can extend to secure any part of your application.
## Full-Stack Vue Development with Nhost
[Section titled “Full-Stack Vue Development with Nhost”](#full-stack-vue-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/vue/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/vue/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/vue/2-protected-routes)
[**Current** - Route protection basics](/getting-started/tutorials/vue/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/vue/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/vue/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/vue/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/vue/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/vue/5-file-uploads)
[File upload and management](/getting-started/tutorials/vue/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* An [Nhost project](/getting-started/tutorials/vue/1-introduction) set up
* Node.js 22+ installed
* Basic knowledge of Vue and Vue Router
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create a New Vue App
[Section titled “Create a New Vue App”](#create-a-new-vue-app)
We’ll start by creating a fresh Vue application using Vite with TypeScript support. Vite provides fast development server and optimized builds for modern Vue applications.
```bash
npm create vue@latest nhost-vue-tutorial -- --typescript --router
cd nhost-vue-tutorial
npm install
```
### Install Required Dependencies
[Section titled “Install Required Dependencies”](#install-required-dependencies)
Install the Nhost JavaScript SDK. The Nhost SDK handles authentication, while Vue Router (already included) enables protected route navigation.
```bash
npm install @nhost/nhost-js
```
### Environment Configuration
[Section titled “Environment Configuration”](#environment-configuration)
Configure your Nhost project connection by creating environment variables. This allows the app to connect to your specific Nhost backend.
Create a `.env` file in your project root:
```bash
VITE_NHOST_REGION=
61
{#if children}
62
{@render children()}
63
{/if}
64
65
Please sign in
104
* Welcome, {{ user?.displayName }}!
105
*
106
* ```
107
*/
108
export function useAuth() {
109
// Initialize auth if not already done
110
if (!isInitialized && typeof window !== "undefined") {
111
initializeAuth();
112
}
113
114
return {
115
user: computed(() => authState.user),
116
session: computed(() => authState.session),
117
isLoading: computed(() => authState.isLoading),
118
isAuthenticated: computed(() => !!authState.session),
119
nhost,
120
};
121
}
122
123
// Initialize auth immediately (for SSR compatibility)
124
if (typeof window !== "undefined") {
125
initializeAuth();
126
}
127
128
// Cleanup on window unload
129
if (typeof window !== "undefined") {
130
window.addEventListener("beforeunload", cleanup);
131
}
````
### Create the Profile Page
[Section titled “Create the Profile Page”](#create-the-profile-page)
Create a page that displays user information. Note that the page itself doesn’t need any special authentication logic - the route protection is handled entirely by the Vue Router navigation guard we set up in the previous step.
src/views/ProfileView\.vue
```vue
1
2
3
8
9
4
5
Loading...
6
7
10
11
13
14
45
46
47
```
### Create a Simple Home Page
[Section titled “Create a Simple Home Page”](#create-a-simple-home-page)
Build a public homepage that adapts its content based on authentication status. This shows users different options depending on whether they’re signed in.
src/views/HomeView\.vue
```vue
1
2
Your Profile
12
15
37
38
User Information
16
17
36
18
Display Name: {{ user?.displayName || "Not set" }}
19
20
21
Email: {{ user?.email || "Not available" }}
22
23
24
User ID: {{ user?.id || "Not available" }}
25
26
27
Roles: {{ user?.roles?.join(", ") || "None" }}
28
29
30
Email Verified:
31
32
{{ user?.emailVerified ? "✓ Yes" : "✗ No" }}
33
34
35
39
44
Session Information
40
41
43
{{ JSON.stringify(session, null, 2) }}
42
3
4
6
7
14
15
16
```
### Create the Navigation Component
[Section titled “Create the Navigation Component”](#create-the-navigation-component)
Create a reusable navigation component that provides consistent navigation across all pages. This component adapts its links based on authentication status - showing different options for signed-in and signed-out users.
src/components/Navigation.vue
```vue
1
2
24
25
26
```
### Configure Protected Routes with Vue Router
[Section titled “Configure Protected Routes with Vue Router”](#configure-protected-routes-with-vue-router)
Set up Vue Router to handle route protection using navigation guards. This approach provides centralized route protection and automatic redirects for unauthenticated users.
src/router/index.ts
```typescript
1
import { createRouter, createWebHistory } from "vue-router";
2
import { useAuth } from "../lib/nhost/auth";
3
import HomeView from "../views/HomeView.vue";
4
import ProfileView from "../views/ProfileView.vue";
5
6
const router = createRouter({
7
history: createWebHistory(import.meta.env.BASE_URL),
8
routes: [
9
{
10
path: "/",
11
name: "home",
12
component: HomeView,
13
},
14
{
15
path: "/profile",
16
name: "profile",
17
component: ProfileView,
18
meta: { requiresAuth: true },
19
},
20
{
21
path: "/:pathMatch(.*)*",
22
redirect: "/",
23
},
24
],
25
});
26
27
// Navigation guard for protected routes
28
router.beforeEach((to) => {
29
if (to.meta["requiresAuth"]) {
30
const { isAuthenticated, isLoading } = useAuth();
31
32
// Show loading state while authentication is being checked
33
if (isLoading.value) {
34
// You can return a loading component path or handle loading in the component
35
return true; // Allow navigation, handle loading in component
36
}
37
38
if (!isAuthenticated.value) {
39
return "/"; // Redirect to home page
40
}
41
}
42
return true;
43
});
44
45
export default router;
```
### Update the Main App Component
[Section titled “Update the Main App Component”](#update-the-main-app-component)
Configure the application’s main component to include the navigation bar and router view. Since we’ve configured route protection in the router itself, the App component mainly needs to provide the layout structure.
src/App.vue
```vue
1
2
Welcome to Nhost Vue Demo
5
8
10
Hello, {{ user?.displayName || user?.email }}!
9
11
13
You are not signed in.
12
3
8
9
10
```
### Add Application Styles
[Section titled “Add Application Styles”](#add-application-styles)
Replace the contents of the file `src/assets/main.css` with the following styles to provide a clean and modern look for the application. This file will be used across the rest of series.
src/assets/main.css
```css
1
:root {
2
font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
3
line-height: 1.5;
4
font-weight: 400;
5
6
color-scheme: dark;
7
color: rgba(255, 255, 255, 0.87);
8
background-color: #242424;
9
10
font-synthesis: none;
11
text-rendering: optimizeLegibility;
12
-webkit-font-smoothing: antialiased;
13
-moz-osx-font-smoothing: grayscale;
14
}
15
16
body {
17
margin: 0;
18
display: flex;
19
place-items: center;
20
min-width: 320px;
21
min-height: 100vh;
22
}
23
24
#app {
25
width: 100%;
26
min-height: 100vh;
27
display: block;
28
margin: 0;
29
padding: 0;
30
}
31
32
a {
33
font-weight: 500;
34
color: #646cff;
35
text-decoration: inherit;
36
}
37
38
a:hover {
39
color: #535bf2;
40
}
41
42
h1 {
43
font-size: 3.2em;
44
line-height: 1.1;
45
}
46
47
button {
48
border-radius: 8px;
49
border: 1px solid transparent;
50
padding: 0.6em 1.2em;
51
font-size: 1em;
52
font-weight: 500;
53
font-family: inherit;
54
background-color: #1a1a1a;
55
cursor: pointer;
56
transition: border-color 0.25s;
57
}
58
59
button:hover {
60
border-color: #646cff;
61
}
62
63
button:focus,
64
button:focus-visible {
65
outline: 4px auto -webkit-focus-ring-color;
66
}
67
68
input,
69
textarea {
70
width: 100%;
71
padding: 0.875rem 1rem;
72
border: 1px solid rgba(255, 255, 255, 0.2);
73
border-radius: 8px;
74
font-size: 0.875rem;
75
transition: all 0.2s ease;
76
background: rgba(255, 255, 255, 0.05);
77
color: white;
78
box-sizing: border-box;
79
font-family: inherit;
80
}
81
82
input:focus,
83
textarea:focus {
84
outline: none;
85
border-color: #3b82f6;
86
box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
87
background: rgba(255, 255, 255, 0.08);
88
}
89
90
input::placeholder,
91
textarea::placeholder {
92
color: rgba(255, 255, 255, 0.5);
93
}
94
95
textarea {
96
resize: vertical;
97
min-height: 4rem;
98
}
99
100
label {
101
display: block;
102
margin: 0 0 0.5rem 0;
103
font-weight: 500;
104
color: rgba(255, 255, 255, 0.9);
105
font-size: 0.875rem;
106
}
107
108
@keyframes spin {
109
0% {
110
transform: rotate(0deg);
111
}
112
100% {
113
transform: rotate(360deg);
114
}
115
}
116
117
/* Global Layout */
118
.app-content {
119
padding: 0 2rem 2rem;
120
max-width: 800px;
121
margin: 0 auto;
122
}
123
124
.page-center {
125
text-align: center;
126
padding: 2rem;
127
}
128
129
.page-header {
130
margin-bottom: 2rem;
131
}
132
133
.page-title {
134
font-weight: 700;
135
margin: 0;
136
display: flex;
137
align-items: center;
138
gap: 1rem;
139
}
140
141
.margin-bottom {
142
margin-bottom: 1rem;
143
}
144
145
.margin-top {
146
margin-top: 1rem;
147
}
148
149
.container {
150
width: 800px;
151
max-width: calc(100vw - 4rem);
152
min-width: 320px;
153
margin: 0 auto;
154
padding: 2rem;
155
box-sizing: border-box;
156
position: relative;
157
}
158
159
/* Status Messages */
160
.success-message {
161
padding: 1rem;
162
background-color: #d4edda;
163
color: #155724;
164
border-radius: 8px;
165
margin-bottom: 1rem;
166
}
167
168
.error-message {
169
background: rgba(239, 68, 68, 0.1);
170
color: #ef4444;
171
border: 1px solid rgba(239, 68, 68, 0.3);
172
border-radius: 12px;
173
padding: 1rem 1.5rem;
174
margin: 1rem 0;
175
}
176
177
.help-text {
178
color: #666;
179
}
180
181
.verification-status {
182
color: #28a745;
183
font-size: 1.2rem;
184
font-weight: bold;
185
margin-bottom: 1rem;
186
}
187
188
.verification-status.error {
189
color: #dc3545;
190
font-size: 1.1rem;
191
}
192
193
/* Email Verification Status */
194
.email-verified {
195
color: #10b981;
196
font-weight: bold;
197
margin-left: 0.5rem;
198
}
199
200
.email-unverified {
201
color: #ef4444;
202
font-weight: bold;
203
margin-left: 0.5rem;
204
}
205
206
/* Debug Info */
207
.debug-panel {
208
margin-bottom: 1rem;
209
padding: 1rem;
210
background-color: #f8f9fa;
211
border-radius: 8px;
212
text-align: left;
213
max-height: 200px;
214
overflow: auto;
215
}
216
217
.debug-title {
218
font-weight: bold;
219
margin-bottom: 0.5rem;
220
}
221
222
.debug-item {
223
margin-bottom: 0.25rem;
224
}
225
226
.debug-key {
227
font-family: monospace;
228
color: #007bff;
229
}
230
231
.debug-value {
232
font-family: monospace;
233
}
234
235
/* Session Display */
236
.session-display {
237
font-size: 0.75rem;
238
overflow: auto;
239
margin: 0;
240
line-height: 1.4;
241
white-space: pre-wrap;
242
word-break: break-word;
243
}
244
245
/* Loading Spinner */
246
.spinner-verify {
247
width: 32px;
248
height: 32px;
249
border: 3px solid #f3f3f3;
250
border-top: 3px solid #007bff;
251
border-radius: 50%;
252
animation: spin 1s linear infinite;
253
margin: 0 auto;
254
}
255
256
/* Navigation */
257
.navigation {
258
background: rgba(255, 255, 255, 0.05);
259
backdrop-filter: blur(10px);
260
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
261
position: sticky;
262
top: 0;
263
z-index: 100;
264
margin-bottom: 2rem;
265
}
266
267
.nav-container {
268
max-width: 800px;
269
margin: 0 auto;
270
padding: 1rem 2rem;
271
display: flex;
272
justify-content: space-between;
273
align-items: center;
274
}
275
276
.nav-logo {
277
font-size: 1.25rem;
278
font-weight: 700;
279
color: white;
280
text-decoration: none;
281
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
282
-webkit-background-clip: text;
283
-webkit-text-fill-color: transparent;
284
background-clip: text;
285
}
286
287
.nav-logo:hover {
288
opacity: 0.8;
289
}
290
291
.nav-links {
292
display: flex;
293
align-items: center;
294
gap: 1.5rem;
295
}
296
297
.nav-link {
298
color: rgba(255, 255, 255, 0.8);
299
text-decoration: none;
300
font-weight: 500;
301
font-size: 0.875rem;
302
padding: 0.5rem 0.75rem;
303
border-radius: 6px;
304
transition: all 0.2s ease;
305
border: none;
306
background: none;
307
cursor: pointer;
308
font-family: inherit;
309
}
310
311
.nav-link:hover {
312
color: white;
313
background: rgba(255, 255, 255, 0.1);
314
}
315
316
.nav-button {
317
color: #ef4444;
318
}
319
320
.nav-button:hover {
321
background: rgba(239, 68, 68, 0.2);
322
}
323
324
/* Buttons */
325
.btn {
326
padding: 0.75rem 1.5rem;
327
border: none;
328
border-radius: 8px;
329
font-weight: 500;
330
cursor: pointer;
331
transition: all 0.2s ease;
332
font-size: 0.875rem;
333
display: inline-flex;
334
align-items: center;
335
justify-content: center;
336
gap: 0.5rem;
337
min-width: 120px;
338
}
339
340
.btn-primary {
341
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
342
color: white;
343
}
344
345
.btn-primary:hover {
346
transform: translateY(-1px);
347
box-shadow: 0 4px 12px rgba(59, 130, 246, 0.4);
348
}
349
350
.btn-secondary {
351
background: rgba(255, 255, 255, 0.1);
352
color: white;
353
border: 1px solid rgba(255, 255, 255, 0.2);
354
}
355
356
.btn-secondary:hover {
357
background: rgba(255, 255, 255, 0.2);
358
}
359
360
.btn-cancel {
361
background: rgba(239, 68, 68, 0.1);
362
color: #ef4444;
363
border: 1px solid rgba(239, 68, 68, 0.3);
364
}
365
366
.btn-cancel:hover {
367
background: rgba(239, 68, 68, 0.2);
368
}
369
370
/* Loading State */
371
.loading-container {
372
display: flex;
373
justify-content: center;
374
align-items: center;
375
padding: 4rem 2rem;
376
}
377
378
.loading-content {
379
display: flex;
380
align-items: center;
381
gap: 1rem;
382
}
383
384
.spinner {
385
width: 2rem;
386
height: 2rem;
387
border: 3px solid rgba(59, 130, 246, 0.3);
388
border-top: 3px solid #3b82f6;
389
border-radius: 50%;
390
animation: spin 1s linear infinite;
391
}
392
393
.loading-text {
394
color: rgba(255, 255, 255, 0.7);
395
font-size: 0.875rem;
396
}
397
398
/* Empty State */
399
.empty-state {
400
text-align: center;
401
padding: 4rem 2rem;
402
background: rgba(255, 255, 255, 0.02);
403
border: 1px solid rgba(255, 255, 255, 0.1);
404
border-radius: 16px;
405
}
406
407
.empty-icon {
408
width: 4rem;
409
height: 4rem;
410
color: rgba(255, 255, 255, 0.4);
411
margin: 0 auto 1rem;
412
}
413
414
.empty-title {
415
font-size: 1.25rem;
416
font-weight: 600;
417
color: white;
418
margin: 0 0 0.5rem 0;
419
}
420
421
.empty-description {
422
color: rgba(255, 255, 255, 0.6);
423
margin: 0;
424
}
425
426
/* Forms */
427
.form-card {
428
background: rgba(255, 255, 255, 0.05);
429
backdrop-filter: blur(10px);
430
border: 1px solid rgba(255, 255, 255, 0.1);
431
border-radius: 16px;
432
padding: 2rem;
433
margin-bottom: 2rem;
434
width: 100%;
435
box-sizing: border-box;
436
}
437
438
.form-title {
439
font-size: 1.5rem;
440
font-weight: 600;
441
color: white;
442
margin: 0 0 1.5rem 0;
443
}
444
445
.form-fields {
446
display: flex;
447
flex-direction: column;
448
gap: 1.5rem;
449
}
450
451
.field-group {
452
display: flex;
453
flex-direction: column;
454
}
455
456
.form-actions {
457
display: flex;
458
gap: 1rem;
459
margin-top: 1rem;
460
}
461
462
/* Auth Pages */
463
.auth-form {
464
max-width: 400px;
465
}
466
467
.auth-form-field {
468
margin-bottom: 1rem;
469
}
470
471
.auth-input {
472
width: 100%;
473
padding: 0.5rem;
474
margin-top: 0.25rem;
475
}
476
477
.auth-error {
478
color: red;
479
margin-bottom: 1rem;
480
padding: 0.5rem;
481
background-color: #fee;
482
border-radius: 4px;
483
}
484
485
.auth-button {
486
width: 100%;
487
padding: 0.75rem;
488
color: white;
489
border: none;
490
border-radius: 4px;
491
cursor: pointer;
492
}
493
494
.auth-button:disabled {
495
cursor: not-allowed;
496
}
497
498
.auth-button.primary {
499
background-color: #28a745;
500
}
501
502
.auth-button.secondary {
503
background-color: #007bff;
504
}
505
506
.auth-links {
507
margin-top: 1rem;
508
}
509
510
/* Todos */
511
512
.todo-form {
513
width: 100%;
514
}
515
516
/* Todo List */
517
.todos-list {
518
display: flex;
519
flex-direction: column;
520
gap: 1rem;
521
}
522
523
.todo-card {
524
background: rgba(255, 255, 255, 0.03);
525
backdrop-filter: blur(10px);
526
border: 1px solid rgba(255, 255, 255, 0.1);
527
border-radius: 12px;
528
transition: all 0.2s ease;
529
overflow: hidden;
530
width: 100%;
531
box-sizing: border-box;
532
}
533
534
.todo-card:hover {
535
border-color: rgba(255, 255, 255, 0.2);
536
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
537
}
538
539
.todo-card.completed {
540
opacity: 0.7;
541
}
542
543
/* Todo Content */
544
.todo-content {
545
padding: 1rem 1.5rem;
546
}
547
548
.todo-edit {
549
padding: 1.5rem;
550
min-height: 200px;
551
}
552
553
.edit-fields {
554
display: flex;
555
flex-direction: column;
556
gap: 1rem;
557
}
558
559
.edit-actions {
560
display: flex;
561
gap: 1rem;
562
margin-top: 1.5rem;
563
}
564
565
.todo-header {
566
display: flex;
567
justify-content: space-between;
568
align-items: center;
569
gap: 1rem;
570
}
571
572
.todo-title-btn {
573
background: none;
574
border: none;
575
padding: 0;
576
text-align: left;
577
font-size: 1.25rem;
578
font-weight: 600;
579
color: white;
580
cursor: pointer;
581
transition: color 0.2s ease;
582
flex: 1;
583
line-height: 1.4;
584
word-wrap: break-word;
585
overflow-wrap: break-word;
586
max-width: calc(100% - 140px);
587
}
588
589
.todo-title-btn:hover {
590
color: #3b82f6;
591
}
592
593
.todo-title-btn.completed {
594
text-decoration: line-through;
595
color: rgba(255, 255, 255, 0.5);
596
}
597
598
.todo-actions {
599
display: flex;
600
gap: 0.5rem;
601
flex-shrink: 0;
602
min-width: 132px;
603
justify-content: flex-end;
604
}
605
606
/* Action Buttons */
607
.action-btn {
608
width: 40px;
609
height: 40px;
610
border: none;
611
border-radius: 6px;
612
cursor: pointer;
613
background: rgba(255, 255, 255, 0.05);
614
display: flex;
615
align-items: center;
616
justify-content: center;
617
font-size: 18px;
618
transition: all 0.2s ease;
619
-webkit-text-fill-color: currentColor;
620
}
621
622
.action-btn-complete {
623
color: #10b981;
624
font-size: 20px;
625
}
626
627
.action-btn-complete:hover {
628
background: rgba(16, 185, 129, 0.2);
629
color: #34d399;
630
}
631
632
.action-btn-edit {
633
color: #3b82f6;
634
}
635
636
.action-btn-edit:hover {
637
background: rgba(59, 130, 246, 0.2);
638
color: #60a5fa;
639
}
640
641
.action-btn-delete {
642
color: #ef4444;
643
}
644
645
.action-btn-delete:hover {
646
background: rgba(239, 68, 68, 0.2);
647
color: #f87171;
648
}
649
650
/* Add Todo Button */
651
.add-todo-btn {
652
width: 36px;
653
height: 36px;
654
border: none;
655
border-radius: 6px;
656
cursor: pointer;
657
background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
658
display: flex;
659
align-items: center;
660
justify-content: center;
661
color: white;
662
font-size: 18px;
663
font-weight: normal;
664
-webkit-text-fill-color: white;
665
transition: all 0.2s ease;
666
}
667
668
.add-todo-btn:hover {
669
transform: scale(1.1);
670
box-shadow: 0 4px 20px rgba(59, 130, 246, 0.4);
671
}
672
673
/* Todo Details */
674
.todo-details {
675
margin-top: 1rem;
676
padding-top: 1rem;
677
border-top: 1px solid rgba(255, 255, 255, 0.1);
678
}
679
680
.description {
681
background: rgba(255, 255, 255, 0.02);
682
border: 1px solid rgba(255, 255, 255, 0.1);
683
border-radius: 8px;
684
padding: 1rem;
685
margin-bottom: 1rem;
686
}
687
688
.description p {
689
margin: 0;
690
color: rgba(255, 255, 255, 0.8);
691
line-height: 1.6;
692
}
693
694
.description.completed p {
695
text-decoration: line-through;
696
color: rgba(255, 255, 255, 0.5);
697
}
698
699
.todo-meta {
700
display: flex;
701
justify-content: space-between;
702
align-items: center;
703
gap: 1rem;
704
}
705
706
.meta-dates {
707
display: flex;
708
gap: 1rem;
709
flex-wrap: wrap;
710
}
711
712
.meta-item {
713
font-size: 0.75rem;
714
color: rgba(255, 255, 255, 0.5);
715
}
716
717
.completion-badge {
718
display: flex;
719
align-items: center;
720
gap: 0.25rem;
721
font-size: 0.75rem;
722
color: #10b981;
723
font-weight: 500;
724
}
725
726
.completion-icon {
727
width: 0.875rem;
728
height: 0.875rem;
729
}
730
731
/* Responsive Design */
732
@media (max-width: 768px) {
733
.nav-container {
734
padding: 1rem;
735
flex-direction: column;
736
gap: 1rem;
737
}
738
739
.nav-links {
740
gap: 1rem;
741
flex-wrap: wrap;
742
justify-content: center;
743
}
744
745
.container {
746
padding: 1rem;
747
}
748
749
.form-actions {
750
flex-direction: column;
751
}
752
753
.edit-actions {
754
flex-direction: column;
755
}
756
757
.todo-header {
758
flex-direction: column;
759
align-items: flex-start;
760
gap: 1rem;
761
}
762
763
.todo-actions {
764
align-self: stretch;
765
justify-content: center;
766
}
767
768
.meta-dates {
769
flex-direction: column;
770
gap: 0.25rem;
771
}
772
773
.todo-meta {
774
flex-direction: column;
775
align-items: flex-start;
776
gap: 0.5rem;
777
}
778
}
779
780
/* File Upload */
781
.file-upload-btn {
782
min-height: 120px;
783
flex-direction: column;
784
gap: 0.5rem;
785
width: 100%;
786
border: 2px dashed rgba(255, 255, 255, 0.3);
787
display: flex;
788
align-items: center;
789
justify-content: center;
790
cursor: pointer;
791
transition: all 0.2s ease;
792
}
793
794
.file-upload-btn:hover {
795
border-color: rgba(255, 255, 255, 0.5);
796
background-color: rgba(255, 255, 255, 0.05);
797
}
798
799
.file-upload-info {
800
margin-top: 0.5rem;
801
font-size: 0.875rem;
802
color: rgba(255, 255, 255, 0.8);
803
}
804
805
/* File Table */
806
.file-table {
807
width: 100%;
808
border-collapse: collapse;
809
}
810
811
.file-table th {
812
padding: 0.75rem;
813
text-align: left;
814
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
815
color: rgba(255, 255, 255, 0.7);
816
font-weight: 500;
817
font-size: 0.875rem;
818
}
819
820
.file-table th:last-child {
821
text-align: center;
822
}
823
824
.file-table td {
825
padding: 0.75rem;
826
border-bottom: 1px solid rgba(255, 255, 255, 0.05);
827
}
828
829
.file-table tr:hover {
830
background-color: rgba(255, 255, 255, 0.02);
831
}
832
833
.file-name {
834
color: white;
835
font-weight: 500;
836
}
837
838
.file-meta {
839
color: rgba(255, 255, 255, 0.6);
840
font-size: 0.875rem;
841
}
842
843
.file-actions {
844
display: flex;
845
gap: 0.5rem;
846
justify-content: center;
847
}
848
849
/* Responsive File Table */
850
@media (max-width: 768px) {
851
.file-table {
852
font-size: 0.875rem;
853
}
854
855
.file-table th,
856
.file-table td {
857
padding: 0.5rem;
858
}
859
860
.file-actions {
861
flex-direction: column;
862
gap: 0.25rem;
863
}
864
}
```
### Run and test the Application
[Section titled “Run and test the Application”](#run-and-test-the-application)
Start the development server to test your route protection implementation:
```bash
npm run dev
```
Things to try out:
1. Try navigating to `/profile` - you should be redirected to the homepage `/` since you’re not authenticated.
2. Because you are not signed in, the navigation bar should only show the “Home” link and the placeholder for signin/signup links.
3. On the homepage, you should see a message indicating that you are not signed in.
After we complete the next tutorial on user authentication, you will be able to sign in and access the protected `/profile` page and see how the navigation bar and homepage updates accordingly.
## How It Works
[Section titled “How It Works”](#how-it-works)
1. **useAuth Composable**: Manages authentication state using Nhost’s client and provides reactive state through Vue’s composition API
2. **Vue Router Guards**: Navigation guards check authentication status before allowing access to protected routes
3. **Profile Page**: A protected page that displays user information, only accessible when authenticated
4. **Automatic Redirects**: Unauthenticated users are redirected to `/`, authenticated users can access `/profile`
## Key Features Demonstrated
[Section titled “Key Features Demonstrated”](#key-features-demonstrated)
Route Protection
Routes are protected using Vue Router navigation guards and authentication composable, preventing unauthorized access to sensitive areas.
Loading States
Smooth loading indicators are shown during authentication checks to improve user experience.
Automatic Redirects
Users are automatically redirected based on their authentication status, ensuring proper navigation flow.
Cross-tab Synchronization
Authentication state is synchronized across multiple browser tabs using Nhost’s session storage events.
Session Management
Complete user session and profile information is displayed and managed throughout the application.
# User Authentication in Vue
> Add sign up, sign in, sign out, and email verification to your Vue app with Nhost Auth and reactive composables for session state.
This tutorial part builds upon the [Protected Routes part](/getting-started/tutorials/vue/2-protected-routes) by adding complete email/password authentication with email verification functionality. You’ll implement sign up, sign in, email verification, and sign out features to create a full authentication flow.
Note
This is **Part 3** in the Full-Stack Vue Development with Nhost series. This part creates a production-ready authentication system with secure email verification and proper error handling.
## Full-Stack Vue Development with Nhost
[Section titled “Full-Stack Vue Development with Nhost”](#full-stack-vue-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/vue/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/vue/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/vue/2-protected-routes)
[Route protection basics](/getting-started/tutorials/vue/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/vue/3-user-authentication)
[**Current** - Complete auth flow](/getting-started/tutorials/vue/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/vue/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/vue/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/vue/5-file-uploads)
[File upload and management](/getting-started/tutorials/vue/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [Protected Routes part](/getting-started/tutorials/vue/2-protected-routes) first
* The project from the previous part set up and running
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create the Sign In Page
[Section titled “Create the Sign In Page”](#create-the-sign-in-page)
Build a comprehensive sign-in form with proper error handling and loading states. This page handles user authentication and includes special logic for post-verification sign-in.
src/views/SignIn.vue
```vue
1
2
5
7
3
47
48
49
```
### Create the Sign Up Page
[Section titled “Create the Sign Up Page”](#create-the-sign-up-page)
Implement user registration with email verification flow. This page collects user information, creates accounts, and guides users through the email verification process.
src/views/SignUp.vue
```vue
1
2
Sign In
4 5 40 41
42
46
43
Don't have an account?
3
73
74
75
```
### Create the Email Verification Page
[Section titled “Create the Email Verification Page”](#create-the-email-verification-page)
Build a dedicated verification page that exchanges authorization codes for sessions using PKCE. This page handles the verification flow when users click the email verification link.
src/views/Verify.vue
```vue
1
2
Sign Up
4Check Your Email
5 6 17 18 66 67
68
72
69
Already have an account?
3
50
51
52
```
Caution
**Important Configuration Required:** Before testing email verification, you must configure your Nhost project’s authentication settings:
1. Go to your Nhost project dashboard
2. Navigate to **Auth → Settings → Authentication**
3. Add your local development URL (e.g., `http://localhost:5173`) to the **Allowed Redirect URLs** field
4. Ensure your production domain is also added when deploying
Without this configuration, you’ll receive a `redirectTo not allowed` error when users attempt to sign up or verify their email addresses.
### Update Router Configuration
[Section titled “Update Router Configuration”](#update-router-configuration)
Update your router configuration to include the new authentication routes:
src/router/index.ts
```ts
1
import { createRouter, createWebHistory } from "vue-router";
2
import { useAuth } from "../lib/nhost/auth";
3
import HomeView from "../views/HomeView.vue";
4
import ProfileView from "../views/ProfileView.vue";
5
import SignIn from "../views/SignIn.vue";
6
import SignUp from "../views/SignUp.vue";
7
import Verify from "../views/Verify.vue";
8
9
const router = createRouter({
10
history: createWebHistory(import.meta.env.BASE_URL),
11
routes: [
12
{
13
path: "/",
14
name: "home",
15
component: HomeView,
16
},
17
{
18
path: "/signin",
19
name: "SignIn",
20
component: SignIn,
21
},
22
{
23
path: "/signup",
24
name: "SignUp",
25
component: SignUp,
26
},
27
{
28
path: "/verify",
29
name: "Verify",
30
component: Verify,
31
},
32
{
33
path: "/profile",
34
name: "profile",
35
component: ProfileView,
36
meta: { requiresAuth: true },
37
},
38
{
39
path: "/:pathMatch(.*)*",
40
redirect: "/",
41
},
42
],
43
});
44
45
// Navigation guard for protected routes
46
router.beforeEach((to) => {
47
if (to.meta["requiresAuth"]) {
48
const { isAuthenticated, isLoading } = useAuth();
49
50
// Show loading state while authentication is being checked
51
if (isLoading.value) {
52
// You can return a loading component path or handle loading in the component
53
return true; // Allow navigation, handle loading in component
54
}
55
56
if (!isAuthenticated.value) {
57
return "/"; // Redirect to home page
58
}
59
}
60
return true;
61
});
62
63
export default router;
```
### Add Navigation Links and Sign Out Functionality
[Section titled “Add Navigation Links and Sign Out Functionality”](#add-navigation-links-and-sign-out-functionality)
Update the navigation component to include links to the sign-in and sign-up pages, and implement the sign-out.
src/components/Navigation.vue
```vue
1
2
35
36
37
```
### Run and Test the Application
[Section titled “Run and Test the Application”](#run-and-test-the-application)
Start your development server and test the complete authentication flow to ensure everything works properly.
```bash
npm run dev
```
Things to try out:
1. Try signing up with a new email address. Check your email for the verification link and click it. See how you are sent to the verification page and then redirected to your profile.
2. Try signing out and then signing back in with the same credentials.
3. Notice how navigation links change based on authentication state showing “Sign In” and “Sign Up” when logged out, and “Profile” and “Sign Out” when logged in.
4. Check how the homepage also reflects the authentication state with appropriate messages.
5. Open multiple tabs and test signing out from one tab to see how other tabs respond. Now sign back in and see the changes propagate across tabs.
## Key Features Demonstrated
[Section titled “Key Features Demonstrated”](#key-features-demonstrated)
Complete Registration Flow
Full email/password registration with proper form validation and user feedback.
Email Verification
Custom `/verify` endpoint that securely processes email verification tokens.
Error Handling
Comprehensive error handling for unverified emails, failed authentication, and network issues.
Visual Feedback
Loading states, success messages, and clear error displays throughout the authentication flow.
Session Management
Complete sign out functionality and proper session state management across the application.
# GraphQL Operations in Vue
> Learn how to perform GraphQL operations and manage database permissions while building a complete todos application with Nhost and Vue
This part builds upon the previous parts by demonstrating how to perform GraphQL operations with proper [database permissions](/products/graphql/permissions). You’ll learn how to design database tables, configure user permissions, and implement complete CRUD operations through GraphQL queries and mutations in a real todos application.
Note
This is **Part 4** in the Full-Stack Vue Development with Nhost series. This part focuses on GraphQL operations, database management, and permission-based data access control in a production application.
## Full-Stack Vue Development with Nhost
[Section titled “Full-Stack Vue Development with Nhost”](#full-stack-vue-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/vue/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/vue/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/vue/2-protected-routes)
[Route protection basics](/getting-started/tutorials/vue/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/vue/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/vue/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/vue/4-graphql-operations)
[**Current** - CRUD operations with GraphQL](/getting-started/tutorials/vue/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/vue/5-file-uploads)
[File upload and management](/getting-started/tutorials/vue/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [User Authentication part](/getting-started/tutorials/vue/3-user-authentication) first
* The project from the previous part set up and running
## What You’ll Build
[Section titled “What You’ll Build”](#what-youll-build)
By the end of this part, you’ll have:
* **GraphQL queries and mutations** for complete CRUD operations
* **Database schema** with proper relationships and constraints
* **User permissions** for secure data access control
* **Vue components** that interact with GraphQL endpoint
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create the To-Dos Table
[Section titled “Create the To-Dos Table”](#create-the-to-dos-table)
First, we’ll perform the database changes to set up the todos table with proper schema and relationships to users.
In your Nhost project dashboard:
1. Navigate to **Database**
2. Click on **SQL Console**
Enter the following SQL:
* SQL
```sql
CREATE TABLE public.todos (
id uuid DEFAULT gen_random_uuid() NOT NULL,
created_at timestamptz DEFAULT now() NOT NULL,
updated_at timestamptz DEFAULT now() NOT NULL,
title text NOT NULL,
details text,
completed bool DEFAULT false NOT NULL,
user_id uuid NOT NULL,
PRIMARY KEY (id),
FOREIGN KEY (user_id) REFERENCES auth.users (id) ON UPDATE CASCADE ON DELETE CASCADE
);
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = now();
RETURN NEW;
END;
$$ language 'plpgsql';
CREATE TRIGGER update_todos_updated_at
BEFORE UPDATE ON public.todos
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();
```
* UI
Caution
Please make sure to enable **Track this** so that the new table todos is available through the auto-generated APIs
### Set Up Permissions
[Section titled “Set Up Permissions”](#set-up-permissions)
It’s now time to set permission rules for the table you just created. With the table `todos` selected, click on **…**, followed by **Edit Permissions**. You will set permissions for the **user** role and actions **insert**, **select**, **update**, and **delete**.
* Insert
When inserting permissions we are only allowing users to set the `title`, `details`, and `completed` columns as the rest of the columns are set automatically by the backend. The `user_id` column is configured as a preset to the currently authenticated user’s ID using the `X-Hasura-User-Id` session variable. This ensures that each todo is associated with the user who created it.
* Select
For selecting (reading) todos, we are allowing to read all columns but only for rows where the `user_id` matches the authenticated user’s ID. This ensures that users can only see their own todos.
* Update
When updating todos, we are allowing users to modify the `title`, `details`, and `completed` columns but only for rows where the `user_id` matches their own ID. This prevents users from modifying todos that do not belong to them.
* Delete
For deleting todos, we are allowing users to delete rows only where the `user_id` matches their own ID. This ensures that users cannot delete todos that belong to other users.
### Create the Todos Page Component
[Section titled “Create the Todos Page Component”](#create-the-todos-page-component)
Now let’s implement the Vue component that uses the database we just configured.
src/views/Todos.vue
```vue
1
2
5
6
Email Verification
4 5
6
49
7
10
11
Verifying your email...
8 9
12
17
18
13 ✓ Successfully verified! 14
15You'll be redirected to your profile page shortly...
16
19
48
20 Verification failed 21
22{{ error }}
23 24
25
39
40
47
26 URL Parameters: 27
28
33
34
{{ key }}:
35
36
{{ value }}
37
38
7
8
21
22
25
26
216
217
218
```
### Update Router Configuration
[Section titled “Update Router Configuration”](#update-router-configuration)
Add the todos page to your application routing.
src/router/index.ts
```ts
1
import { createRouter, createWebHistory } from "vue-router";
2
import { useAuth } from "../lib/nhost/auth";
3
import HomeView from "../views/HomeView.vue";
4
import ProfileView from "../views/ProfileView.vue";
5
import SignIn from "../views/SignIn.vue";
6
import SignUp from "../views/SignUp.vue";
7
import Todos from "../views/Todos.vue";
8
import Verify from "../views/Verify.vue";
9
10
const router = createRouter({
11
history: createWebHistory(import.meta.env.BASE_URL),
12
routes: [
13
{
14
path: "/",
15
name: "home",
16
component: HomeView,
17
},
18
{
19
path: "/signin",
20
name: "SignIn",
21
component: SignIn,
22
},
23
{
24
path: "/signup",
25
name: "SignUp",
26
component: SignUp,
27
},
28
{
29
path: "/verify",
30
name: "Verify",
31
component: Verify,
32
},
33
{
34
path: "/profile",
35
name: "profile",
36
component: ProfileView,
37
meta: { requiresAuth: true },
38
},
39
{
40
path: "/todos",
41
name: "Todos",
42
component: Todos,
43
meta: { requiresAuth: true },
44
},
45
{
46
path: "/:pathMatch(.*)*",
47
redirect: "/",
48
},
49
],
50
});
51
52
// Navigation guard for protected routes
53
router.beforeEach((to) => {
54
if (to.meta["requiresAuth"]) {
55
const { isAuthenticated, isLoading } = useAuth();
56
57
// Show loading state while authentication is being checked
58
if (isLoading.value) {
59
// You can return a loading component path or handle loading in the component
60
return true; // Allow navigation, handle loading in component
61
}
62
63
if (!isAuthenticated.value) {
64
return "/"; // Redirect to home page
65
}
66
}
67
return true;
68
});
69
70
export default router;
```
### Update Navigation Links
[Section titled “Update Navigation Links”](#update-navigation-links)
Add a link to the todos page in the navigation bar.
src/components/Navigation.vue
```vue
1
2
38
39
40
```
### Test Your Complete Application
[Section titled “Test Your Complete Application”](#test-your-complete-application)
Run your application and test all the functionality:
```bash
npm run dev
```
Things to try out:
1. Try signing in and out and see how the Todos page is only available when authenticated
2. Create, view, edit, complete, and delete todos. See how the UI updates accordingly
3. Open the application in another browser or incognito window, sign in with a different account and verify that you cannot see or modify todos from the first account
## Key Features Implemented
[Section titled “Key Features Implemented”](#key-features-implemented)
Database Schema
Properly designed todos table with constraints, indexes, and automatic timestamp updates for optimal performance.
GraphQL API
Auto-generated GraphQL API with queries and mutations for full CRUD operations on todos.
Row-Level Security
Comprehensive permissions ensuring users can only access their own todos through all GraphQL operations.
CRUD Operations
Complete Create, Read, Update, Delete functionality with proper error handling and user feedback.
Rich Interface
Expandable todo items, inline editing, completion status, and detailed timestamps.
# File Uploads in Vue
> Add file uploads to your Vue app with Nhost Storage: configure buckets and permissions and build a complete file management system.
This part builds upon the previous GraphQL operations part by demonstrating how to implement [file upload functionality](/products/storage) with proper storage permissions. You’ll learn how to create [storage buckets](/products/storage/buckets), configure upload permissions, and implement complete file management operations in a Vue application.
Note
This is **Part 5** in the Full-Stack Vue Development with Nhost series. This part focuses on file storage, upload operations, and permission-based file access control in a production application.
## Full-Stack Vue Development with Nhost
[Section titled “Full-Stack Vue Development with Nhost”](#full-stack-vue-development-with-nhost)
### [1. Create Project](/getting-started/tutorials/vue/1-introduction)
[Set up your Nhost project](/getting-started/tutorials/vue/1-introduction)
### [2. Protected Routes](/getting-started/tutorials/vue/2-protected-routes)
[Route protection basics](/getting-started/tutorials/vue/2-protected-routes)
### [3. User Authentication](/getting-started/tutorials/vue/3-user-authentication)
[Complete auth flow](/getting-started/tutorials/vue/3-user-authentication)
### [4. GraphQL Operations](/getting-started/tutorials/vue/4-graphql-operations)
[CRUD operations with GraphQL](/getting-started/tutorials/vue/4-graphql-operations)
### [5. File Uploads](/getting-started/tutorials/vue/5-file-uploads)
[**Current** - File upload and management](/getting-started/tutorials/vue/5-file-uploads)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Complete the [GraphQL Operations part](/getting-started/tutorials/vue/4-graphql-operations) first
* The project from the previous part set up and running
## What You’ll Build
[Section titled “What You’ll Build”](#what-youll-build)
By the end of this part, you’ll have:
* A **personal bucket** so users can upload their own private files
* **File upload functionality**
* **File management interface** for viewing and deleting files
* **Security permissions** ensuring users can only access their own files
## Step-by-Step Guide
[Section titled “Step-by-Step Guide”](#step-by-step-guide)
### Create a Personal Storage Bucket
[Section titled “Create a Personal Storage Bucket”](#create-a-personal-storage-bucket)
First, we’ll create a storage bucket where users can upload their personal files.
In your Nhost project dashboard:
1. Navigate to **Storage**
2. Click **New Bucket** in the sidebar
3. Set the name to `personal` and click **Save**
### Configure Storage Permissions
[Section titled “Configure Storage Permissions”](#configure-storage-permissions)
Now we need to set up permissions for the storage bucket to ensure the `user` role can only upload, view, and delete their own files.
In the dashboard, navigate to **Storage** and click **Permissions** to open the permission grid.
* Upload
Click the **Upload** cell for the `user` role.
1. Select **With custom check** and add a rule: `bucket_id` equals `personal`
2. Enable the **Uploader identity** toggle — this automatically sets `uploaded_by_user_id` to the current user’s ID on every upload, so you can reference it in Download and Delete rules.
* Download
Click the **Download** cell for the `user` role.
1. Select **With custom check** and add two rules combined with AND:
* `bucket_id` equals `personal`
* `uploaded_by_user_id` equals `X-Hasura-User-Id`
* Delete
Click the **Delete** cell for the `user` role.
1. Select **With custom check** and add the same two rules as Download:
* `bucket_id` equals `personal`
* `uploaded_by_user_id` equals `X-Hasura-User-Id`
Note
You can read more about storage permissions [here](/products/storage/permissions)
### Create the File Upload Component
[Section titled “Create the File Upload Component”](#create-the-file-upload-component)
Now let’s implement the Vue component for file upload functionality.
src/views/Files.vue
```vue
1
2
9 My Todos 10 19
20
27
63
64
65
66
215
67
72
73
68
69
Loading todos...
70
71
74
214
75
89
94
95
No todos yet
9091 Create your first todo to get started! 92
93
101
213
102
137
138
103
136
104
105
110
111
112
113
118
119
120
127
134
135
139
212
140
147
174
175
148
156
164
172
173
176
211
180
182
183
210
{{ todo.details }}
181
3
4
6
7
160
161
162
```
### Update Router Configuration
[Section titled “Update Router Configuration”](#update-router-configuration)
Add the files page to your application routing.
src/router/index.ts
```ts
1
import { createRouter, createWebHistory } from "vue-router";
2
import { useAuth } from "../lib/nhost/auth";
3
import Files from "../views/Files.vue";
4
import HomeView from "../views/HomeView.vue";
5
import ProfileView from "../views/ProfileView.vue";
6
import SignIn from "../views/SignIn.vue";
7
import SignUp from "../views/SignUp.vue";
8
import Todos from "../views/Todos.vue";
9
import Verify from "../views/Verify.vue";
10
11
const router = createRouter({
12
history: createWebHistory(import.meta.env.BASE_URL),
13
routes: [
14
{
15
path: "/",
16
name: "home",
17
component: HomeView,
18
},
19
{
20
path: "/signin",
21
name: "SignIn",
22
component: SignIn,
23
},
24
{
25
path: "/signup",
26
name: "SignUp",
27
component: SignUp,
28
},
29
{
30
path: "/verify",
31
name: "Verify",
32
component: Verify,
33
},
34
{
35
path: "/profile",
36
name: "profile",
37
component: ProfileView,
38
meta: { requiresAuth: true },
39
},
40
{
41
path: "/todos",
42
name: "Todos",
43
component: Todos,
44
meta: { requiresAuth: true },
45
},
46
{
47
path: "/files",
48
name: "Files",
49
component: Files,
50
meta: { requiresAuth: true },
51
},
52
{
53
path: "/:pathMatch(.*)*",
54
redirect: "/",
55
},
56
],
57
});
58
59
// Navigation guard for protected routes
60
router.beforeEach((to) => {
61
if (to.meta["requiresAuth"]) {
62
const { isAuthenticated, isLoading } = useAuth();
63
64
// Show loading state while authentication is being checked
65
if (isLoading.value) {
66
// You can return a loading component path or handle loading in the component
67
return true; // Allow navigation, handle loading in component
68
}
69
70
if (!isAuthenticated.value) {
71
return "/"; // Redirect to home page
72
}
73
}
74
return true;
75
});
76
77
export default router;
```
### Update Navigation Links
[Section titled “Update Navigation Links”](#update-navigation-links)
Add a link to the files page in the navigation bar.
src/components/Navigation.vue
```vue
1
2
41
42
43
```
### Test Your File Upload System
[Section titled “Test Your File Upload System”](#test-your-file-upload-system)
Run your application and test all the functionality:
```bash
npm run dev
```
Things to try out:
1. Try signing in and out and see how the file upload page is only accessible when signed in.
2. Upload different types of files (images, documents, etc.)
3. View and delete files
4. Sign in with another account and verify you cannot see files from the first account
## Key Features Implemented
[Section titled “Key Features Implemented”](#key-features-implemented)
Storage Bucket
Dedicated personal storage bucket with proper configuration for user file isolation.
File Upload Interface
User-friendly upload interface with file selection, preview, and progress feedback.
File Management
Complete file listing with metadata, viewing capabilities, and deletion functionality.
File Type Handling
Intelligent handling of different file types with appropriate viewing/download behavior.
Error Handling
Comprehensive error handling with user-friendly messages for upload and management operations.
# Platform
> Learn about platform features
# Explore different deployment options
### [Cloud](/platform/cloud)
[Fully managed backend infrastructure](/platform/cloud)
### [Development](/platform/cli)
[Develop your project with Nhost](/platform/cli)
### [Self-Hosting](/platform/self-hosting)
[Run Nhost on your own infrastructure](/platform/self-hosting)
# CLI Overview
> Develop with Nhost using local and cloud development workflows
The Nhost CLI provides flexible development workflows that adapt to your needs. Whether you prefer running everything locally for complete control or developing against cloud infrastructure for team collaboration, the CLI supports both approaches with seamless integration.
## Development Workflows
[Section titled “Development Workflows”](#development-workflows)
### [Local Development](/platform/cli/local-development)
[Run the complete Nhost stack locally for offline development, fast iteration, and full control over your environment.](/platform/cli/local-development)
### [Cloud Development](/platform/cli/cloud-development)
[Develop against cloud infrastructure while maintaining local tools for simplified remote testing and team collaboration.](/platform/cli/cloud-development)
## Key Features
[Section titled “Key Features”](#key-features)
### Complete Stack Control
Run PostgreSQL, GraphQL, Auth, Storage, and custom services either locally or connected to cloud infrastructure.
### Fast Iteration
Make changes to your schema, auth settings, or storage permissions and see them take effect instantly.
### Configuration as Code
Define your project’s configuration in version-controlled files for easy collaboration and deployment.
## Getting Started
[Section titled “Getting Started”](#getting-started)
### [CLI Quickstart](/getting-started/local-development/cli)
[Install the CLI, initialize a project, and spin up your local backend in minutes](/getting-started/local-development/cli)
### [Local Development](/platform/cli/local-development)
[Set up and run the complete Nhost stack locally for offline development](/platform/cli/local-development)
### [Cloud Development](/platform/cli/cloud-development)
[Develop against cloud projects while maintaining local development tools](/platform/cli/cloud-development)
## Advanced Features
[Section titled “Advanced Features”](#advanced-features)
### [Configuration Overlays](/platform/cli/configuration-overlays)
[Manage environment-specific settings without duplicating your base configuration](/platform/cli/configuration-overlays)
### [Custom Subdomains](/platform/cli/subdomain)
[Configure dynamic DNS to connect from different devices to your local project](/platform/cli/subdomain)
### [Multiple Projects](/platform/cli/multiple-projects)
[Work on multiple projects simultaneously with isolated environments](/platform/cli/multiple-projects)
### [Seed Data](/platform/cli/seeds)
[Populate your development database with test data for consistent environments](/platform/cli/seeds)
## Choose Your Workflow
[Section titled “Choose Your Workflow”](#choose-your-workflow)
**New to Nhost?** Start with [Local Development](/platform/cli/local-development) to run everything on your machine and get familiar with the platform.
**Working with a team?** Try [Cloud Development](/platform/cli/cloud-development) to develop against shared cloud infrastructure while maintaining local development tools.
Both workflows support the same powerful features and can be used together as your project evolves.
# Cloud Development
> Develop against a cloud-hosted Nhost project with a minimal local setup, automatic migration tracking, and Git-based deployments.
Nhost’s cloud development workflow allows you to develop against a cloud-hosted project while maintaining a minimal local environment. This approach combines the benefits of cloud infrastructure with local development tools, enabling seamless collaboration and deployment workflows.
## Benefits of Cloud Development
[Section titled “Benefits of Cloud Development”](#benefits-of-cloud-development)
Cloud development with Nhost offers several key advantages:
* **Minimal local setup**: Run only essential development tools locally while leveraging cloud infrastructure
* **Automatic tracking**: Database migrations and metadata changes are automatically captured in your local repository
* **Git-based deployments**: Connect your repository to staging and production environments for streamlined deployments
* **Simplified testing**: Connect your frontend directly to cloud services, making remote testing and third-party integrations straightforward
## Create a Cloud Project
[Section titled “Create a Cloud Project”](#create-a-cloud-project)
First, let’s set up a new project in the Nhost Cloud Console.
1. **Create a new project** in the [Nhost Cloud Console](https://app.nhost.io)
2. **Note your project details** from the overview page:
* Project subdomain
* Region
3. **Enable database public access**:
* Navigate to **Database** → **Settings** → **Access** 
* Enable **Public Access**
* Click **Save**
4. **Configure database password**:
* In the same Database settings, open **Reset password** 
* Set a new password for your database
* Click **Save**
* Note the connection string displayed under **Access**
Note
Your final PostgreSQL URL will be the connection string with `[YOUR-PASSWORD]` replaced by the password you just set.
## Initialize Your Local Repository
[Section titled “Initialize Your Local Repository”](#initialize-your-local-repository)
Now let’s connect your local development environment to the cloud project.
```bash
nhost init --remote
```
This command will:
* Prompt you to sign in to your Nhost account
* Display a list of your cloud projects
* Allow you to select the project you want to work with
* Create the necessary configuration files in your local directory
## Start the Local Development Environment
[Section titled “Start the Local Development Environment”](#start-the-local-development-environment)
With your repository initialized, you can now start the local development environment connected to your cloud project.
```bash
export SUBDOMAIN=your-project-subdomain
export POSTGRES_URL=your-complete-postgres-url
nhost up cloud --subdomain $SUBDOMAIN --postgres-url $POSTGRES_URL
```
Replace the placeholder values with:
* `your-project-subdomain`: The subdomain noted in step 2
* `your-complete-postgres-url`: The connection string with your password from step 4
This command starts a local development environment that connects to your cloud infrastructure while providing local access to the Nhost dashboard and console.
## Making Changes to Your Project
[Section titled “Making Changes to Your Project”](#making-changes-to-your-project)
With your local development environment running, always use the local interfaces to make changes to your project.
### Development Interfaces
[Section titled “Development Interfaces”](#development-interfaces)
Access your local development tools at:
* **Console**: File Upload
5
8
75
76
Upload a File
9 10
11
28
57
58
59
60
61
64
65
74
77
159
Your Files
78 79
83
{{ deleteStatus.message }}
84
85
86
87
92
88
89
Loading files...
90
91
93
107
110
No files yet
108Upload your first file to get started!
109
111
112
113
157
158
| Name | 115Type | 116Size | 117Actions | 118
|---|---|---|---|
| {{ file.name }} | 123{{ file.mimeType }} | 124{{ formatFileSize(file.size || 0) }} | 125
126
127
143
152
153
|
154
400 Bad Request
Verify You Email
Hi, ${displayName}! Please click the link to verify your email:
``` # Postmark Integration [Section titled “Postmark Integration”](#postmark-integration) Alternatively, you can use postmark’s native integration and leverage postmark’s templates. To do so, you need to: 1. Configure SMTP settings like below: ```toml [provider.smtp] host = 'postmark' password = '{{ secrets.POSTMARK_API_KEY }}' sender = 'myapp@mydomain.com' ``` Caution It is very important that the `host` is set exactly to `postmark`. 2. In postmark you need to create three templates for each locale with the following alias: * $locale.email-confirm-change * $locale.email-verify * $locale.password-reset For instance: * en.email-confirm-change * en.email-verify * en.password-reset * se.email-confirm-change * se.email-verify * se.password-reset Additionally, if you want to use the [passwordless sign-in](/products/auth/sign-in-magic-link) or OTP sign-in emails, you need to create the following templates as well: * $locale.signin-passwordless * $locale.signin-otp * $locale.elevate-otp After these two steps have been completed, the Auth service will leverage these templates instead of the ones described in the previous section. Note Postmark templates should have access to the same variables as described [previously](#template-variables) # Gravatar > Fetch user profiles automatically from gravatar ## Gravatar [Section titled “Gravatar”](#gravatar) If Gravatar is enabled, Nhost Auth will use the user’s email address to fetch their Gravatar profile picture. If the user doesn’t have a Gravatar profile picture, a default image will be used. There are two options for Gravatars. ### Default Image [Section titled “Default Image”](#default-image) If the user doesn’t have a Gravatar profile picture, a default image will be used. You can choose between the following options: * `404`: Do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response. * `mp`: (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash). * `identicon`: a geometric pattern based on an email hash. * `monsterid`: a generated ‘monster’ with different colors, faces, etc. * `wavatar`: generated faces with differing features and backgrounds. * `retro`: awesome generated, 8-bit arcade-style pixelated faces. * `robohash`: a generated robot with different colors, faces, etc. * `blank`: a transparent PNG image. ### Rating [Section titled “Rating”](#rating) Gravatar images are rated by default. You can choose between the following options: * `g`: suitable for display on all websites with any audience type. * `pg`: may contain rude gestures, provocatively dressed individuals, lesser swear words or mild violence. * `r`: may contain such things as harsh profanity, intense violence, nudity, or hard drug use. * `x`: may contain hardcore sexual imagery or extremely disturbing violence. # JSON Web Tokens (JWTs) > Configure how Nhost Auth signs JWT access tokens using symmetric keys, asymmetric keys, or an external signing service. ## Introduction [Section titled “Introduction”](#introduction) JSON Web Tokens (JWT) are encoded strings designed to securely transmit information between parties in the form of a JSON object. Each JWT consists of three parts: * header * payload * signature JWTs are commonly used for authentication post-login. The server generates a token containing user claims (like identity and permissions) that subsequent requests can include to prove authorization. Here’s how JWTs typically work in an authentication flow: 1. User logs in with credentials (username/password) 2. Server validates credentials and generates a signed JWT containing user information and permissions 3. Server sends the JWT to the client, which stores it (usually in browser storage) 4. For subsequent requests, the client includes the JWT in the Authorization header 5. Server verifies the token’s signature and grants access based on the encoded permissions The main advantage is that the server doesn’t need to store session information - all necessary data is contained within the token itself, making it ideal for stateless authentication. Note For more information about JSON Web Tokens, visit [jwt.io](https://jwt.io). ## JWT Configuration [Section titled “JWT Configuration”](#jwt-configuration) You can configure your project to use three different kinds of JWTs: * JWTs signed with symmetric keys * JWTs signed with asymmetric keys * JWTs signed externally via a third-party service Note Currently we default to using symmetric keys for signing JWTs. However, we plan to change this to use asymmetric keys in the near future. ### Symmetric Keys [Section titled “Symmetric Keys”](#symmetric-keys) With symmetric keys, your project uses a single key for both signing and verifying JWTs. This key is stored in the project’s configuration and is responsible for signing JWTs. When a client sends a JWT to the server, the server uses the same key to verify the JWT’s signature. If you need to verify JWTs in a different service, the same key can be used for verification. Since the same key is used for both signing and verification, it is crucial to keep it secret, as sharing it with others can compromise the security of your JWTs. Below you can see an example of a symmetric key configuration: * nhost.toml ```toml [[hasura.jwtSecrets]] type = 'HS256' key = 'f03d5f5a0ed055e3fcbc0a3639405aca0511e6abe6d60e40d1fff610c6248f2a' ``` * dashboard  Note We recommend using a [secret](/platform/cloud/secrets) to configure the key. In addition to `HS256`, you can also use `HS384` and `HS512` for extra security. To quickly generate a key, you can use the following command: * HS256 ```shell openssl rand -base64 32 ``` * HS384 ```shell openssl rand -base64 48 ``` * HS512 ```shell openssl rand -base64 64 ``` ### Asymmetric Keys [Section titled “Asymmetric Keys”](#asymmetric-keys) With asymmetric keys, your project uses a pair of public and private keys for signing and verifying JWTs. The private key, stored securely in the project’s configuration, is used to sign the JWTs. The public key, on the other hand, is made available to clients and is used to verify the JWTs. When a client sends a JWT to the server, the server uses the public key to validate the JWT’s signature. If verification is needed in a different service, the public key can be used without compromising security. Since the public key is only used for verification and the private key for signing, sharing the public key is safe and does not jeopardize the security of your JWTs. Below you can see an example of an asymmetric key configuration: * nhost.toml ```toml [[hasura.jwtSecrets]] type = "RS256" kid = "bskhwtelkajsd" key = "" -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqSFS8Kx9LuiYpIms+NoZ (omitted for brevity) jwIDAQAB -----END PUBLIC KEY----- "" signingKey = "" -----BEGIN PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCpIVLwrH0u6Jik (omitted for brevity) s6fJmz3ZeArPI8KFSI3Q2xqm -----END PRIVATE KEY----- "" ``` * dashboard  In addition to `RS256`, you can also use `RS384` and `RS512` for extra security. To quickly generate a key pair, you can use the following commands: * RS256 ```shell # Generate a private key openssl genpkey -algorithm RSA -out jwt_private.pem -pkeyopt rsa_keygen_bits:2048 # Generate a public key from the private key openssl rsa -pubout -in jwt_private.pem -out jwt_public.pem ``` * RS384 ```shell # Generate a private key openssl genpkey -algorithm RSA -out jwt_private.pem -pkeyopt rsa_keygen_bits:3072 # Generate a public key from the private key openssl rsa -pubout -in jwt_private.pem -out jwt_public.pem ``` * RS512 ```shell # Generate a private key openssl genpkey -algorithm RSA -out jwt_private.pem -pkeyopt rsa_keygen_bits:4096 # Generate a public key from the private key openssl rsa -pubout -in jwt_private.pem -out jwt_public.pem ``` You can then copy the contents of `jwt_private.pem` into the `signingKey` field and the contents of `jwt_public.pem` into the `key` field. The `kid` value in your configuration can be any unique string of your choice and must be distinct for each key. It is used to identify the correct key when verifying JWTs through the JWKS endpoint. ### External Signing [Section titled “External Signing”](#external-signing) If you are using a third party service like Auth0 or Clerk you can configure your project to use their JWK endpoint to verify JWTs. Below you can see an example of an external signing configuration: * nhost.toml ```toml [[hasura.jwtSecrets]] jwk_url = "https://mythirdpartyservice.com/jwks.json" ``` Alternatively, you can configure the public key directly: ```toml [[hasura.jwtSecrets]] type = "RS256" key = "" -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqSFS8Kx9LuiYpIms+NoZ (omitted for brevity) jwIDAQAB -----END PUBLIC KEY----- "" ``` * dashboard  Note When using external signing the Auth service will be automatically disabled. ### Claims Mapping and Namespace [Section titled “Claims Mapping and Namespace”](#claims-mapping-and-namespace) When verifying tokens — especially those issued by an external provider — you can remap their claims onto the session variables your permissions expect, and control where those claims are read from. The `claims_namespace` defaults to `https://hasura.io/jwt/claims` (a [retained identifier](/products/graphql/configuration#naming-conventions) kept for compatibility) and can be overridden with `claims_namespace` or `claims_namespace_path`. Use `claims_map` to project individual claims from a literal value or a JSON path within the token. * nhost.toml ```toml [[hasura.jwtSecrets]] jwk_url = "https://my-auth-server.com/.well-known/jwks.json" issuer = "https://my-auth-server.com" [[hasura.jwtSecrets.claims_map]] claim = "x-some-claim" value = "some-value" [[hasura.jwtSecrets.claims_map]] claim = "x-other-claim" path = "$.user.claim.id" default = "default-value" ``` * Schema ```cue #JWTSecret: ({ type: "HS384" | "HS512" | *"HS256" key: string } | { type: "RS256" | "RS384" | "RS512" key: string signingKey?: string kid?: string } | { jwk_url: #Url | *null }) & { claims_format?: "stringified_json" | *"json" audience?: string issuer?: string allowed_skew?: uint32 header?: string } & { claims_map?: [...#ClaimMap] } & ({ claims_namespace: string | *"https://hasura.io/jwt/claims" } | { claims_namespace_path: string } | *{}) #ClaimMap: { claim: string { value: string } | { path: string default?: string } } ``` The complete `#JWTSecret` schema, with every field and default, is documented in the [configuration reference](/reference/configuration#jwtsecret). ## Verify a JWT [Section titled “Verify a JWT”](#verify-a-jwt) To verify JWTs inside Nhost Functions (for both symmetric and asymmetric keys), see the [JWT Verification guide](/products/functions/guides/jwt-verification). ## Custom Claims [Section titled “Custom Claims”](#custom-claims) You can attach extra information to your JWTs in the form of custom claims. These claims can be used for authorization purposes in your application. For more details on how to add custom claims to your JWTs and how to use them, see the [Permissions Variables](/products/graphql/permissions/permission-variables) documentation. # Multi-Factor Authentication (MFA) > Learn how to add TOTP-based multi-factor authentication to your application for enhanced security. Multi-Factor Authentication adds an extra layer of security by requiring a verification code from an authenticator app (e.g., [Authy](https://authy.com/), [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator)) in addition to the user’s email and password. ## Configuration [Section titled “Configuration”](#configuration) To enable MFA, navigate to **Auth -> Settings -> Authentication** and enable **Multi-Factor Authentication**. You can also configure it using the `nhost.toml` file: nhost.toml ```toml [auth.totp] enabled = true ``` ## Enabling MFA [Section titled “Enabling MFA”](#enabling-mfa) Once MFA is enabled for your project, individual users can activate it on their account. This is a two-step process: ### Step 1: Generate TOTP Secret [Section titled “Step 1: Generate TOTP Secret”](#step-1-generate-totp-secret) Request a TOTP secret and QR code for the user to scan with their authenticator app: ```js const response = await nhost.auth.changeUserMfa(); // Display the QR code image for the user to scan const imageUrl = response.body.imageUrl; // Or show the totpSecret for manual entry const totpSecret = response.body.totpSecret; ``` ### Step 2: Verify and Activate [Section titled “Step 2: Verify and Activate”](#step-2-verify-and-activate) After the user scans the QR code, they enter the 6-digit verification code from their authenticator app to confirm activation: ```js await nhost.auth.verifyChangeUserMfa({ activeMfaType: 'totp', code: '123456', // 6-digit code from authenticator app }); ``` ### Activation Flow [Section titled “Activation Flow”](#activation-flow) ```mermaid sequenceDiagram autonumber actor U as User participant C as Client participant A as Nhost Auth participant G as Authenticator App U-->A: Authenticated C->>+A: GET /mfa/totp/generate A->>-C: QR code image URL + TOTP secret C->>U: Display QR code U->>+G: Scan QR code G->>-U: 6-digit TOTP code C->>+A: POST /user/mfa Note right of C: TOTP code + activeMfaType: "totp" A->>A: Verify code and activate MFA A->>-C: OK ``` ## Signing In with MFA [Section titled “Signing In with MFA”](#signing-in-with-mfa) When a user with MFA enabled signs in with email and password, the server returns a `ticket` instead of a session. The client must then prompt for a TOTP code and verify it to complete sign-in. ### Step 1: Initial Sign-In [Section titled “Step 1: Initial Sign-In”](#step-1-initial-sign-in) ```js const response = await nhost.auth.signInEmailPassword({ email: 'joe@example.com', password: 'secret-password', }); if (response.body?.mfa) { // MFA is required — store the ticket and prompt for TOTP const ticket = response.body.mfa.ticket; // Navigate to MFA verification page } ``` ### Step 2: Verify TOTP Code [Section titled “Step 2: Verify TOTP Code”](#step-2-verify-totp-code) ```js const response = await nhost.auth.verifySignInMfaTotp({ ticket: ticket, // from step 1 otp: '123456', // 6-digit code from authenticator app }); // response.body.session contains the access + refresh tokens ``` ### Sign-In with MFA Flow [Section titled “Sign-In with MFA Flow”](#sign-in-with-mfa-flow) ```mermaid sequenceDiagram autonumber actor U as User participant C as Client participant A as Nhost Auth participant G as Authenticator App U->>C: Enter email + password C->>+A: POST /signin/email-password A->>-C: MFA ticket C->>U: Prompt for TOTP code U->>+G: Open authenticator app G->>-U: 6-digit TOTP code U->>C: Enter TOTP code C->>+A: POST /signin/mfa/totp Note right of C: ticket + TOTP code A->>A: Verify TOTP A->>-C: Session (access + refresh tokens) ``` ## Disabling MFA [Section titled “Disabling MFA”](#disabling-mfa) Users can disable MFA by providing a current TOTP code from their authenticator app: ```js await nhost.auth.verifyChangeUserMfa({ activeMfaType: '', // empty string disables MFA code: '123456', // current 6-digit code from authenticator app }); ``` # OAuth2 / OIDC Provider > Use your Nhost project as an OAuth2 and OpenID Connect Identity Provider for third-party applications Nhost Auth can act as an OAuth2 Authorization Server and OpenID Connect Identity Provider. This lets third-party applications — wikis, dashboards, MCP servers, internal tools — authenticate users through your Nhost project using standard OAuth2/OIDC flows. ```mermaid sequenceDiagram participant App as Third-Party App participant Auth as Nhost Auth participant Consent as Your Consent Page App->>Auth: Redirect to /oauth2/authorize Auth->>Consent: Redirect with request_id Consent->>Consent: User authenticates & approves Consent->>Auth: POST /oauth2/login Auth->>App: Redirect with authorization code App->>Auth: Exchange code for tokens Auth->>App: Access token, ID token, refresh token ``` ## What It Supports [Section titled “What It Supports”](#what-it-supports) * **Three client types** — confidential (with secret), public (no secret, PKCE required), and URL-based (CIMD) * **Scopes** — `openid`, `profile`, `email`, `phone`, `offline_access`, `graphql` * **RSA-signed JWT tokens** — access tokens and ID tokens signed with RSA (RS256, RS384, or RS512), with a JWKS endpoint for verification ## Standards Compliance [Section titled “Standards Compliance”](#standards-compliance) | Standard | Description | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) | OAuth 2.0 Authorization Framework — Authorization Code grant | | [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) | OAuth 2.0 Bearer Token Usage | | [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009) | Token Revocation — Refresh token revocation | | [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) | JSON Web Key (JWK) — JWKS endpoint for public signing keys | | [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) | JSON Web Token (JWT) — RSA-signed access and ID tokens | | [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) | PKCE — Proof Key for Code Exchange (S256 only) | | [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) | Token Introspection — Check token validity | | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) | Authorization Server Metadata — Discovery endpoints | | [RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207) | Issuer Identification — `iss` parameter in authorization responses | | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) | Client ID Metadata Document — URL-based client IDs for MCP and similar tools | | [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) | ID tokens, UserInfo, Discovery, standard claims | ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * An **[RSA signing key](/products/auth/jwt#asymmetric-keys)** must be configured. Other algorithms are not supported when the OAuth2 provider is enabled. * The OAuth2 provider must be **explicitly enabled** via configuration. ## Configuration [Section titled “Configuration”](#configuration) * Dashboard Go to your project’s dashboard, then **Auth** → **Settings** → **OAuth2 Provider**.  * nhost.toml ```toml [auth.oauth2Provider] # Enable the OAuth2/OIDC provider enabled = true # default: false # URL where users are redirected for login and consent # You need to implement this page yourself, check our guides for details loginURL = 'https://example.com/oauth2/login' [auth.oauth2Provider.accessToken] # Access token lifetime in seconds expiresIn = 900 # default: 900 - 15 minutes [auth.oauth2Provider.refreshToken] # Refresh token lifetime in seconds expiresIn = 2592000 # default: 2592000 - 30 days [auth.oauth2Provider.clientIdMetadataDocument] # Enable URL-based client IDs per RFC 9728, used by MCP and similar tools enabled = true # default: false ``` ## Next Steps [Section titled “Next Steps”](#next-steps) ### [Managing Clients](/products/auth/oauth2-provider/managing-clients) [Create and manage OAuth2 clients via GraphQL](/products/auth/oauth2-provider/managing-clients) ### [Authorization Code Flow](/products/auth/oauth2-provider/authorization-flow) [Understand the flow and build your consent page](/products/auth/oauth2-provider/authorization-flow) ### [Tokens and Scopes](/products/auth/oauth2-provider/tokens-and-scopes) [Understand token formats, scopes, and claims](/products/auth/oauth2-provider/tokens-and-scopes) # Authorization Code Flow > Understand the OAuth2 authorization code flow and build your consent page When a third-party app wants to authenticate one of your users, it triggers the Authorization Code flow. This is a standard OAuth2 flow where three parties are involved: | Party | Who | Role | | --------------------- | ----------------------------------------------- | -------------------------------------------------- | | **Third-Party App** | The external service (e.g. a wiki, an MCP tool) | Initiates the flow and receives tokens | | **Nhost Auth** | Your Nhost project’s auth service | Validates requests, issues codes and tokens | | **Your Consent Page** | A page **you build** in your frontend | Authenticates the user and collects their approval | ```mermaid sequenceDiagram participant App as Third-Party App participant Auth as Nhost Auth participant Consent as Your Consent Page App->>Auth: Redirect to /oauth2/authorize Auth->>Auth: Validate client, redirect_uri, scopes Auth->>Consent: Redirect with request_id Consent->>Auth: GET /oauth2/login?request_id=(includes codeChallenge) A->>-P: 302 Redirect to provider authorization P->>P: User authorizes application P->>+A: Callback with authorization code Note over A: Exchange code for provider tokens
Create/update user
Generate authorization code A->>-C: 302 Redirect to redirectTo with ?code=... C->>C: Consume verifier from localStorage C->>+A: POST /token/exchange Note right of C: code + codeVerifier A->>A: Validate S256(codeVerifier) == codeChallenge A->>-C: Session (access + refresh tokens) ``` ## Implementation Steps [Section titled “Implementation Steps”](#implementation-steps) ### 1. Generate the Provider Sign-In URL [Section titled “1. Generate the Provider Sign-In URL”](#1-generate-the-provider-sign-in-url) Use `signInProviderURL()` to generate the OAuth authorization URL with a PKCE `codeChallenge`: ```tsx import { generatePKCEPair } from '@nhost/nhost-js/auth'; const handleSocialSignIn = async (provider: 'github' | 'google' | 'apple') => { const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); const url = nhost.auth.signInProviderURL(provider, { redirectTo: `${window.location.origin}/verify`, codeChallenge: challenge, }); window.location.href = url; }; ``` ### 2. OAuth Provider Authorization [Section titled “2. OAuth Provider Authorization”](#2-oauth-provider-authorization) When the user is redirected to the OAuth provider (e.g., GitHub, Google), they will: 1. See a consent screen asking to authorize your application 2. Grant or deny permission to access their profile information 3. Be redirected back to Nhost Auth’s callback URL ### 3. Nhost Auth Callback Processing [Section titled “3. Nhost Auth Callback Processing”](#3-nhost-auth-callback-processing) Nhost Auth receives the callback from the OAuth provider at `/v1/signin/provider/{provider}/callback` and performs the following: 1. **Validates the OAuth state** to prevent CSRF attacks 2. **Exchanges the authorization code** for access and refresh tokens from the provider 3. **Fetches the user’s profile** from the provider 4. **Creates or updates the user** in your Nhost database 5. **Generates an authorization code** bound to the PKCE challenge 6. **Redirects to your client application** with `?code=...` ### 4. Handle the Redirect [Section titled “4. Handle the Redirect”](#4-handle-the-redirect) After successful authentication, Nhost redirects back to your `redirectTo` URL with a `code` query parameter: ```plaintext https://your-app.com/verify?code=abc123... ``` Exchange this code for a session using the stored PKCE verifier. See [Handling the Verification Redirect](/products/auth/pkce#handling-the-verification-redirect) for the complete implementation. ```tsx const params = new URLSearchParams(location.search); const code = params.get('code'); const codeVerifier = localStorage.getItem('nhost_pkce_verifier'); localStorage.removeItem('nhost_pkce_verifier'); await nhost.auth.tokenExchange({ code, codeVerifier }); ``` #### Error Handling [Section titled “Error Handling”](#error-handling) On error, the URL will contain error parameters: ```plaintext https://your-app.com/verify?error=access_denied ``` Common error scenarios include: * User denied authorization at the OAuth provider * Invalid OAuth request configuration * Error from the OAuth provider * Provider account already linked to another user ### 5. Session Management [Section titled “5. Session Management”](#5-session-management) Once you’ve exchanged the authorization code for a session, the Nhost SDK automatically manages: * **Access token** - Short-lived JWT for API requests (default: 15 minutes) * **Refresh token** - Used to obtain new access tokens (default: 30 days) * **Automatic token refresh** - The SDK refreshes tokens before expiration ## Security Considerations [Section titled “Security Considerations”](#security-considerations) ### PKCE Protection [Section titled “PKCE Protection”](#pkce-protection) PKCE prevents authorization code interception attacks by binding the authorization code to the client that initiated the request. The code can only be exchanged by presenting the original `codeVerifier` that matches the `codeChallenge` sent during initiation. ### CSRF Protection [Section titled “CSRF Protection”](#csrf-protection) Nhost automatically handles CSRF protection using the OAuth `state` parameter. Each sign-in request generates a unique state value that is validated during the callback. ### Redirect URL Validation [Section titled “Redirect URL Validation”](#redirect-url-validation) For security, Nhost validates that the `redirectTo` URL matches either your clientUrl or one of your configured allowed redirect URLs. Configure these in your Nhost project under **Auth → Settings → Authentication**. ### Custom Domains [Section titled “Custom Domains”](#custom-domains) To use your own domain for the OAuth callback URL instead of the default Nhost domain, refer to the [custom domains](/platform/cloud/custom-domains) documentation. ## Provider-Specific Setup [Section titled “Provider-Specific Setup”](#provider-specific-setup) Each OAuth provider requires specific configuration. Refer to the provider-specific guides for detailed setup instructions: * [Apple](/products/auth/providers/sign-in-apple) * [Azure AD / Entra ID](/products/auth/providers/sign-in-azuread) * [Bitbucket](/products/auth/providers/sign-in-bitbucket) * [Discord](/products/auth/providers/sign-in-discord) * [Facebook](/products/auth/providers/sign-in-facebook) * [GitHub](/products/auth/providers/sign-in-github) * [GitLab](/products/auth/providers/sign-in-gitlab) * [Google](/products/auth/providers/sign-in-google) * [LinkedIn](/products/auth/providers/sign-in-linkedin) * [Spotify](/products/auth/providers/sign-in-spotify) * [Strava](/products/auth/providers/sign-in-strava) * [Twitch](/products/auth/providers/sign-in-twitch) * [Windows Live](/products/auth/providers/sign-in-windowslive) * [WorkOS](/products/auth/providers/sign-in-workos) ## API Reference [Section titled “API Reference”](#api-reference) For detailed API documentation, see: * [signInProviderURL()](/reference/javascript/nhost-js/auth#signinproviderurl) in the JavaScript SDK reference * [GET /v1/signin/provider/{provider}](/reference/auth/get-signin-provider-%7Bprovider%7D) in the API reference * [GET /v1/signin/provider/{provider}/callback](/reference/auth/get-signin-provider-%7Bprovider%7D-callback) in the API reference # Sign In with Spotify > Enable Spotify OAuth social login with Nhost Auth — create a Spotify app, set redirect URIs, and authenticate users.  ## Create Spotify Account [Section titled “Create Spotify Account”](#create-spotify-account) * Create a new [Spotify account](https://www.spotify.com/) if you don’t have one already. ## Create Spotify App [Section titled “Create Spotify App”](#create-spotify-app) * Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/). * Click on CREATE AN APP. * Fill in an App name and App description. * Check the box to agree Spotify’s [Developer Terms of Service](https://developer.spotify.com/terms) and [Branding Guidelines](https://developer.spotify.com/branding-guidelines). ## Configure OAuth Callback URL [Section titled “Configure OAuth Callback URL”](#configure-oauth-callback-url) * Click EDIT SETTINGS. * A modal appears. * Fill in **Redirect URIs** with your **OAuth Callback URL** from Nhost. * Click ADD to add the OAuth callback URL. * Click SAVE. ## Configure Nhost [Section titled “Configure Nhost”](#configure-nhost) * Click SHOW CLIENT SECRET in the Spotify App Dashboard. * Copy and paste the **Client ID** and **Client Secret** from Spotify to your Nhost OAuth settings for Spotify. * Click the checkbox “**I have pasted the redirect URI into Spotify”**. * Click **Confirm settings**. ## Sign In Users [Section titled “Sign In Users”](#sign-in-users) Once you’ve configured Spotify as an OAuth provider in Nhost, you can sign in users using the Spotify provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. # Sign In with Strava > Add Strava OAuth social login with Nhost Auth — register an API application, configure access, and sign in athletes. Note Due to Strava API updates, email is no longer returned and is intentionally left blank. ## Create Strava Account [Section titled “Create Strava Account”](#create-strava-account) * Create a new [Strava Account](https://www.strava.com/register/free) if you don’t have one already. ## Create Strava OAuth App [Section titled “Create Strava OAuth App”](#create-strava-oauth-app) * Create a new OAuth application [(direct link)](https://www.strava.com/settings/api) by: * Click on your avatar in the top right of the navbar. * Select Settings. * On the left Sidebar, Select My API Application. ## Strava OAuth App Information. [Section titled “Strava OAuth App Information.”](#strava-oauth-app-information) * Enter a Application Name. * Enter the Redirect URI. ## Configure Nhost [Section titled “Configure Nhost”](#configure-nhost) * Click Generate a new client secret to generate an OAuth client secret. * Copy and paste the **Client ID** and **Client Secret** from Strava to your Nhost OAuth settings for Strava. Make sure the OAuth provider is enabled in Nhost. * Click the checkbox “**I have pasted the redirect URI into Strava”**. * Click **Confirm settings**. ## Sign In Users [Section titled “Sign In Users”](#sign-in-users) Once you’ve configured Strava as an OAuth provider in Nhost, you can sign in users using the Strava provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. # Sign In with Twitch > Enable Twitch OAuth social login with Nhost Auth — register an application, set redirect URLs, and sign in users.  ## Create Twitch Account [Section titled “Create Twitch Account”](#create-twitch-account) * Create a new [Twitch account](https://twitch.tv/) if you don’t have one already. ## Create Twitch App [Section titled “Create Twitch App”](#create-twitch-app) * Sign in to the [Twitch Developer Console](https://dev.twitch.tv/console). * Click on **Register Your Application**. * Fill in a **Twitch application name**. * Copy and paste the callback URL from your Nhost OAuth settings for Twitch to the input field under **OAuth Redirect URLs** and click **Add** to the right of the input field. * Select an application **Category**. E.g. *Application Integration*. * Click **Create**. ## Get Twitch Application Client ID and Client Secret [Section titled “Get Twitch Application Client ID and Client Secret”](#get-twitch-application-client-id-and-client-secret) * Click on **Manage** on your newly created Twitch application. * Copy the **Client ID** and paste it into your Nhost OAuth settings for Twitch. * Click on **New Secret** to generate a new client secret. * Copy the **Client Secret** and paste it into your Nhost OAuth settings for Twitch. ## Sign In Users [Section titled “Sign In Users”](#sign-in-users) Once you’ve configured Twitch as an OAuth provider in Nhost, you can sign in users using the Twitch provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. # Sign In with WindowsLive > Add Windows Live (Microsoft) OAuth social login with Nhost Auth — configure an Azure app and sign in Microsoft users. ## Create WindowsLive Account [Section titled “Create WindowsLive Account”](#create-windowslive-account) * Create a new [WindowsLive Account](https://portal.azure.com/) if you don’t have one already. ## Create WindowsLive OAuth App [Section titled “Create WindowsLive OAuth App”](#create-windowslive-oauth-app) * Create a new OAuth application [(direct link)](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) by: * Click on New Registration. * Enter a Name. * Select the supported account types. * Select the supported platform which is **Web**. * Select the Redirect URI. ## WindowsLive OAuth App Information. [Section titled “WindowsLive OAuth App Information.”](#windowslive-oauth-app-information) * Inside essentials dropdown, click on secret near the Client Credentials Field. * Click on new client secret. * Enter a Description. * Select the expiry date from the dropdown. ## Configure Nhost [Section titled “Configure Nhost”](#configure-nhost) * Click Generate a new client secret to generate an OAuth client secret. * Copy and paste the **Client ID** and **Client Secret** from WindowsLive to your Nhost OAuth settings for WindowsLive. Make sure the OAuth provider is enabled in Nhost. * Click the checkbox “**I have pasted the redirect URI into WindowsLive”**. * Click **Confirm settings**. ## Sign In Users [Section titled “Sign In Users”](#sign-in-users) Once you’ve configured WindowsLive as an OAuth provider in Nhost, you can sign in users using the WindowsLive provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. # Sign In with WorkOS > Configure WorkOS with Nhost Auth for enterprise SSO and SAML — connect WorkOS OAuth and sign in organization users.  ## Create WorkOS Account [Section titled “Create WorkOS Account”](#create-workos-account) * Go to [WorkOS’s website](https://workos.com/). * Click on **Sign In** in the top menu and create a WorkOS account. ## Get the Client ID [Section titled “Get the Client ID”](#get-the-client-id) * In the WorkOS dashboard, click on **Configuration** in the left menu. * Copy the **Client ID**, which starts with `project_`. * Paste the **Client ID** in the **Client ID** field in the WorkOS settings in the Nhost Dashboard. ## Set correct Redirect URI [Section titled “Set correct Redirect URI”](#set-correct-redirect-uri) * In the WorkOS dashboard, click on **Configuration** in the left menu. * Click on **Edit Redirect URIs** in the Redirect URIs section. * Add the **Redirect URL** from the Nhost Dashboard to the list of Redirect URIs. * Set the newly added redirect URI as the **Default Redirect URI**. * Click on **Close**. ## Get the Client Secret [Section titled “Get the Client Secret”](#get-the-client-secret) * In the WorkOS dashboard, click on **API Keys** in the left menu. * Click on the eye icon next to the **Client Secret** to reveal it. * Copy the **Client Secret**, which stars with `sk_`. * Paste the **Client Secret** in the **Client Secret** field in the WorkOS settings in the Nhost Dashboard. ## Get Organization ID [Section titled “Get Organization ID”](#get-organization-id) * In the WorkOS dashboard, click on **Organizations** in the left menu. * Click on **Create an Organization**. * Fill in the organization details and click on **Create Organization**. * Click on the newly created organization. * Copy the **Organization ID**, which stars with `org_`. * Paste the **Organization ID** in the **Organization ID** field in the WorkOS settings in the Nhost Dashboard. * Click **Save** in the Nhost Dashboard to save all WorkOS settings. The WorkOS configuration is now completed with Nhost. See the [WorkOS documentation](https://workos.com/docs/) to learn more about how to configure WorkOS. ## Sign In Users [Section titled “Sign In Users”](#sign-in-users) Once you’ve configured WorkOS as an OAuth provider in Nhost, you can sign in users using the WorkOS provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. # OAuth Provider Access Tokens > Access and refresh OAuth provider tokens to interact with external APIs When users authenticate with [OAuth providers](/products/auth/providers) through Nhost, you can access the provider’s access and refresh tokens. This enables your application to make API calls directly to external services (like Google Drive, GitHub repositories, or Spotify playlists) on behalf of your users. ## How Provider Token Management Works [Section titled “How Provider Token Management Works”](#how-provider-token-management-works) After a user completes OAuth authentication, you can retrieve and manage the provider’s tokens to interact with their external accounts: ```mermaid sequenceDiagram autonumber actor U as User participant F as Frontend participant A as Auth participant P as OAuth Provider Note over U,P: Initial OAuth Sign-In U->>+F: Complete OAuth sign-in F->>+A: GET /signin/provider/{provider}/callback/tokens Note right of A: Bearer token required A->>A: Retrieve stored provider session A->>-F: Provider tokens (access, refresh, expiresIn) F->>F: Store tokens securely deactivate F Note over U,P: Using Provider Access Token U->>+F: Request action requiring provider API F->>+P: API call with provider access token P->>-F: API response F->>-U: Result Note over U,P: Refreshing Expired Token F->>F: Detect token expiration F->>+A: POST /token/provider/{provider} Note right of A: Include refresh token A->>+P: Request new access token P->>-A: New access token (+ optional new refresh token) A->>-F: Updated tokens F->>F: Update stored tokens ``` ### The Token Flow [Section titled “The Token Flow”](#the-token-flow) 1. **OAuth Completion**: After the user successfully authenticates with an OAuth provider, they are redirected back to your application 2. **Token Retrieval**: Your frontend immediately calls `/signin/provider/{provider}/callback/tokens` with the user’s Nhost authentication token to retrieve the provider’s tokens 3. **Secure Storage**: The provider’s access token, refresh token, and expiration time are stored securely in your application 4. **Provider API Calls**: Your application uses the provider’s access token to make API calls to the external service on behalf of the user 5. **Token Refresh**: When the access token expires, your application uses the refresh token to obtain a new access token without requiring the user to re-authenticate ## Retrieving Provider Tokens [Section titled “Retrieving Provider Tokens”](#retrieving-provider-tokens) After a successful OAuth sign-in, retrieve the provider’s session to access their tokens. ```javascript import { createClient } from '@nhost/nhost-js' const nhost = createClient({ subdomain: 'myapp', region: 'us-east-1' }) // Immediately after OAuth callback completes const resp = await nhost.auth.getProviderTokens('google') // Store tokens securely localStorage.setItem('google_access_token', resp.body.accessToken) if (resp.body.refreshToken) { localStorage.setItem('google_refresh_token', resp.body.refreshToken) } // Use provider token to call Google APIs const userInfo = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', { headers: { 'Authorization': `Bearer ${resp.body.accessToken}` } }) ``` **Important Notes:** * This method must be called **immediately** after the OAuth callback completes * The provider session is stored temporarily and is cleared during this call * Subsequent calls will fail without re-authenticating with the provider * Requires the user to be authenticated with Nhost ## Refreshing Provider Tokens [Section titled “Refreshing Provider Tokens”](#refreshing-provider-tokens) Provider access tokens typically expire after a short period (often 1 hour). Use the refresh token to obtain a new access token without user interaction. ```javascript import { createClient } from '@nhost/nhost-js' const nhost = createClient({ subdomain: 'myapp', region: 'us-east-1' }) // Retrieve stored refresh token const storedRefreshToken = localStorage.getItem('google_refresh_token') // Refresh the provider tokens const resp = await nhost.auth.refreshProviderToken('google', { refreshToken: storedRefreshToken }) // Update stored tokens localStorage.setItem('google_access_token', resp.body.accessToken) if (resp.body.refreshToken) { // Some providers rotate refresh tokens localStorage.setItem('google_refresh_token', resp.body.refreshToken) } ``` **Important Notes:** * Some providers (like Google) rotate refresh tokens, returning a new one in the response * Always update your stored refresh token with the new value if provided * Token refresh can fail if the user revokes access or the refresh token expires * Handle these cases by prompting the user to re-authenticate ## Best Practices [Section titled “Best Practices”](#best-practices) **Immediate Retrieval** - Call the tokens endpoint immediately after OAuth callback to prevent session loss **Secure Storage** - Store provider tokens in secure storage appropriate for your platform (encrypted storage for mobile, httpOnly cookies or secure localStorage for web) **Proactive Refresh** - Use the `expiresIn` value to refresh tokens before they expire, preventing API call failures **Handle Rotation** - Always update your stored refresh token when a new one is returned, as some providers invalidate old refresh tokens **Graceful Errors** - Handle token refresh failures by prompting users to re-authenticate, as they may have revoked access through the provider’s settings **Token Isolation** - Store tokens per provider and per user to support multiple OAuth connections # Restricting Emails & Domains > Restrict sign-ups by email address or domain ## Allowed Emails and Domains [Section titled “Allowed Emails and Domains”](#allowed-emails-and-domains) Allowed Emails and Domains are used to restrict what email addresses and domains are valid when signing up and signing in. If both allowed emails and allowed domains are set a user can only sign up if their email address matches one of the allowed emails or one of the allowed domains. ## Blocked Emails and Domains [Section titled “Blocked Emails and Domains”](#blocked-emails-and-domains) Blocked Emails and Domains are used to block specific email addresses and domains from signing up and signing in. Note that even if a user’s email address matches any allowed email or domain, they will still be blocked if their email address matches any blocked email or domain. # Anonymous Sign-In > Learn how to let users try your application without creating an account, and how to convert them to permanent users. Anonymous sign-in creates a temporary user without requiring any credentials. This is useful for allowing users to try your application before committing to an account. ## Sign In [Section titled “Sign In”](#sign-in) ```js await nhost.auth.signInAnonymous(); ``` ## Deanonymization [Section titled “Deanonymization”](#deanonymization) Anonymous users can be converted to permanent accounts by linking an email address or a phone number. ### Email [Section titled “Email”](#email) The email deanonymization flow follows the same PKCE pattern as sign-up, using `deanonymizeUser`: ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); // Deanonymize with email + password await nhost.auth.deanonymizeUser({ signInMethod: 'email-password', email: 'joe@example.com', password: 'secret-password', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); // Or deanonymize with passwordless email (magic link) await nhost.auth.deanonymizeUser({ signInMethod: 'passwordless', email: 'joe@example.com', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` After the user verifies their email, the authorization code is [exchanged for a session](/products/auth/pkce#handling-the-verification-redirect). Both email pathways require [PKCE](/products/auth/pkce) via the `codeChallenge` parameter when email verification is required. ### SMS [Section titled “SMS”](#sms) [SMS deanonymization](/products/auth/otp/sms#deanonymize-with-sms) links a phone number without a `codeChallenge`. Requesting deanonymization stages the new phone number and user options while the user remains anonymous. The conversion completes through `/signin/passwordless/sms/otp`: after the OTP is verified, the staged options are applied and a non-anonymous session is returned. # Sign In with Email and Password > Learn about Email and Password authentication, including sign-up, sign-in, email verification, password reset, and email change flows. Sign In with Email and Password is enabled by default on all projects. ## Sign Up [Section titled “Sign Up”](#sign-up) To sign up a new user, use `signUpEmailPassword` with a valid email and password. ### Without Email Verification [Section titled “Without Email Verification”](#without-email-verification) When email verification is disabled, sign-up returns a session directly: ```js const response = await nhost.auth.signUpEmailPassword({ email: 'joe@example.com', password: 'secret-password', }); // response.body.session contains the access + refresh tokens ``` ### With Email Verification [Section titled “With Email Verification”](#with-email-verification) By default, newly registered users must verify their email before they can sign in. To change this, navigate to **Auth -> Settings -> Sign-In Methods -> Email and Password** and set **Require Verified Emails**. When email verification is enabled (the default), pass a `codeChallenge` for [PKCE](/products/auth/pkce) so the verification link can securely establish a session: ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; // Generate PKCE pair and store verifier for later const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); await nhost.auth.signUpEmailPassword({ email: 'joe@example.com', password: 'secret-password', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` Note A newly registered user will receive an email with a verification link. Clicking the link redirects to your app with an authorization `code` that must be [exchanged for a session](/products/auth/pkce#handling-the-verification-redirect). #### Email Verification [Section titled “Email Verification”](#email-verification) The email verification email is sent automatically when the user signs up but, you can manually resend the verification email: ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); await nhost.auth.userEmailSendVerificationEmail({ email: 'joe@example.com', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` Tip It is possible to customize these automatic emails, learn how to [here](/products/auth/email-templates). ## Sign In [Section titled “Sign In”](#sign-in) After a user is registered and verified, they can sign in. Email/password sign-in returns a session directly without PKCE. ```js await nhost.auth.signInEmailPassword({ email: 'joe@example.com', password: 'secret-password', }); ``` Note Email/password sign-in also supports [Multi-Factor Authentication (MFA)](/products/auth/mfa). When MFA is enabled, the sign-in response returns a ticket instead of a session, and the user must provide a TOTP code to complete authentication. ## Password Reset [Section titled “Password Reset”](#password-reset) Users can request a password reset email. The reset flow uses PKCE to securely establish a session so the user can set a new password. ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); await nhost.auth.userPasswordReset({ email: 'joe@example.com', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` After the user clicks the reset link and the authorization code is [exchanged for a session](/products/auth/pkce#handling-the-verification-redirect), the user can set a new password: ```js await nhost.auth.changePassword({ newPassword: 'new-secret-password', }); ``` ## Change Password [Section titled “Change Password”](#change-password) An authenticated user can change their password directly: ```js await nhost.auth.changePassword({ newPassword: 'new-secret-password', }); ``` A user who has completed a [password reset](#password-reset) flow can also set a new password using the session established by the reset link. ## Change Email [Section titled “Change Email”](#change-email) An authenticated user can request an email change. A verification email is sent to the new address using PKCE to securely confirm the change. ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); await nhost.auth.userEmailChange({ newEmail: 'new-joe@example.com', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` # Sign In with a Magic Link > Sign users in with passwordless magic links emailed to them, secured with PKCE and no password required. Magic Links are a type of passwordless login that allow users to sign in by clicking a link emailed to them, rather than typing a password. Magic Links are disabled by default and can be enabled using the Nhost Dashboard under **Auth -> Settings -> Sign-In Methods -> Magic Link**. ## Sign In [Section titled “Sign In”](#sign-in) To sign in users with a Magic Link, use `signInPasswordlessEmail` with an email and a `codeChallenge` for [PKCE](/products/auth/pkce): ```js import { generatePKCEPair } from '@nhost/nhost-js/auth'; const { verifier, challenge } = await generatePKCEPair(); localStorage.setItem('nhost_pkce_verifier', verifier); await nhost.auth.signInPasswordlessEmail({ email: 'joe@example.com', options: { redirectTo: `${window.location.origin}/verify`, }, codeChallenge: challenge, }); ``` After the user clicks the magic link in their email, they’ll be redirected to your app with an authorization code. See [Handling the Verification Redirect](/products/auth/pkce#handling-the-verification-redirect) to exchange the code for a session. Note A user account is created the first time a Magic Link is used. Tip Users who have signed up with email and password can also sign in with a Magic Link. Tip It is possible to customize the email with the Magic Link, learn how to [here](/products/auth/email-templates). ### Sign In Flow [Section titled “Sign In Flow”](#sign-in-flow) ```mermaid sequenceDiagram autonumber actor U as User participant C as Client participant A as Nhost Auth participant E as SMTP Server C->>C: Generate PKCE pair (verifier + challenge) C->>C: Store verifier in localStorage U->>+A: POST /signin/passwordless/email Note right of U: email, codeChallenge opt No user found A->>A: Create user end A->>A: Generate ticket (stores codeChallenge) A-)E: Send magic link email A->>-U: OK E-)U: Receive email U->>+A: GET /verify (follow email link) A->>A: Verify email A->>A: Generate authorization code A->>-C: Redirect with ?code=... C->>C: Consume verifier from localStorage C->>+A: POST /token/exchange Note right of C: code + codeVerifier A->>A: Validate S256(codeVerifier) == codeChallenge A->>-C: Session (access + refresh tokens) ``` # Users > Manage user accounts in Nhost Auth, including default and allowed roles, metadata, and GraphQL permissions on the auth schema. ## Creating Users [Section titled “Creating Users”](#creating-users) Users are created using the sign-up or sign-in flows described under [Supported Methods](/products/auth#supported-methods). * **Avoid** creating users directly via GraphQL or the database, unless you are [importing users](#import-users) from an external system. * **Avoid** modifying the database schema for the `auth.users` table. * **Avoid** modifying the GraphQL root queries or fields for any of the tables in the `auth` schema. You’re allowed to: * Add and remove your GraphQL relationships for the `users` table and other tables in the `auth` schema. * Create, edit and delete permissions for the `users` table and other tables in the `auth` schema. ## Roles [Section titled “Roles”](#roles) Each user has one **default role** and a list of **allowed roles**. These roles are used to resolve permissions for requests to [GraphQL](/products/graphql/permissions) and [Storage](/products/storage/permissions). When the user makes a request, only one role is used to resolve permissions. The default role is used if no role is explicitly specified. Users can only make requests using the default role or one of the allowed roles. ### Default Role [Section titled “Default Role”](#default-role) The default role is used when no role is specified in the request. By default, users’ default role is `user`. You can change what the default role for new users should be at **Auth -> Settings -> Roles and Permissions**. ### Allowed Roles [Section titled “Allowed Roles”](#allowed-roles) Allowed roles are roles the user is allowed to use when making a request. Usually, you would change the role from `user` (the default role) to some other role because you want to use a different role to resolve permissions for a particular request. By default, users have two allowed roles: * `user` (default) * `me` You can change the default role for new users at **Auth -> Settings -> Roles and Permissions**. #### Assign Allowed Roles [Section titled “Assign Allowed Roles”](#assign-allowed-roles) It’s possible to give users a subset of allowed roles during signup. **Example:** Only set the `user` role (exclude the `me` role) for the user’s allowed roles: ```js await nhost.auth.signUp({ email: 'joe@example.com', password: 'secret-password' options: { allowedRoles: ['user'] } }) ``` ### Set Role for GraphQL Requests [Section titled “Set Role for GraphQL Requests”](#set-role-for-graphql-requests) When no role is specified, the user’s default role will be used: ```js await nhost.graphql.request(QUERY, {}) ``` If you want to make a GraphQL request using a specific role, you can do so by using the `x-hasura-role` header, like this: ```js await nhost.graphql.request( QUERY, {}, { headers: { 'x-hasura-role': 'me' } } ) ``` If the request is not part of the user’s allowed roles, the request will fail. ## Metadata [Section titled “Metadata”](#metadata) You can store custom information about the user in the `metadata` column of the `users` table. The `metadata` column is of type JSONB so any JSON data can be stored. **Example:** Add metadata to a user during sign-up: ```js await nhost.auth.signUp({ email: 'joe@example.com', password: 'secret-password', options: { metadata: { birthYear: 1989, town: 'Stockholm', likes: ['Postgres', 'GraphQL', 'Authentication', 'Storage', 'Serverless Functions'] } } }) ``` ## Get User Information using GraphQL [Section titled “Get User Information using GraphQL”](#get-user-information-using-graphql) **Example:** Get all users. ```graphql query { users { id displayName email metadata } } ``` **Example:** Get a single user. ```graphql query { user(id: "
joined {formatRelativeTime(community.my_joined_at)}
)}
) : (
)}
(stripe-graphql-js) participant S as Stripe API C->>G: GraphQL query { stripe { customer { ... } } } G->>F: Forward remote schema query F->>F: Verify JWT / admin secret F->>F: Run isAllowed() check F->>S: Stripe API request S-->>F: Stripe data F-->>G: GraphQL response G-->>C: Unified response ``` Your client sends a single GraphQL query to the GraphQL engine. The engine identifies the `stripe` field as a Remote Schema and forwards it to the Nhost Function running `@nhost/stripe-graphql-js`. The function authenticates the request, checks permissions, fetches data from Stripe, and returns it through the GraphQL engine back to the client. ## Setup [Section titled “Setup”](#setup) 1. **Install the package** In your Nhost project, install the dependency: ```shell pnpm add @nhost/stripe-graphql-js ``` 2. **Create the serverless function** Create a file at `functions/graphql/stripe.ts`: ```ts import { createStripeGraphQLServer } from '@nhost/stripe-graphql-js'; const server = createStripeGraphQLServer(); export default server; ``` 3. **Add the Stripe secret key** First, store your Stripe secret key as a project secret. In the Nhost dashboard go to **Settings** > **Secrets**, or use the CLI: ```shell nhost secrets create STRIPE_SECRET_KEY sk_live_... ``` Then expose it as an environment variable in `nhost/nhost.toml`: ```toml [[global.environment]] name = 'STRIPE_SECRET_KEY' value = '{{ secrets.STRIPE_SECRET_KEY }}' ``` 4. **Register as a Remote Schema** Add the function as a Remote Schema in `nhost/metadata/remote_schemas.yaml`: ```yaml - name: stripe definition: url: '{{NHOST_FUNCTIONS_URL}}/graphql/stripe' timeout_seconds: 60 customization: {} ``` Or add it through the dashboard under **GraphQL** > **Remote Schemas**, using `{{NHOST_FUNCTIONS_URL}}/graphql/stripe` as the URL. ## Available Operations [Section titled “Available Operations”](#available-operations) ### Queries [Section titled “Queries”](#queries) All queries are namespaced under the `stripe` field: | Query | Arguments | Description | | ------------------ | ------------------------------------------------- | ----------------------------------------------------- | | `stripe.customer` | `id` (required) | Get a single customer by ID | | `stripe.customers` | `email`, `limit`, `startingAfter`, `endingBefore` | List customers with optional filtering and pagination | A customer object includes nested fields that resolve additional Stripe data: | Nested Field | Description | | ---------------- | ------------------------------------------------------------------------------------- | | `subscriptions` | Customer’s active subscriptions | | `invoices` | Customer’s invoices | | `paymentMethods` | Customer’s payment methods (accepts `type`, `limit`, `startingAfter`, `endingBefore`) | | `paymentIntents` | Customer’s payment intents | | `charges` | Customer’s charges | Additional root queries (admin only): | Query | Arguments | Description | | -------------------------- | --------------- | --------------------------- | | `stripe.connectedAccount` | `id` (required) | Get a connected account | | `stripe.connectedAccounts` | — | List all connected accounts | ### Mutations [Section titled “Mutations”](#mutations) | Mutation | Arguments | Description | | ----------------------------------- | ------------------------------------------------------------- | -------------------------------------- | | `stripe.createBillingPortalSession` | `customer` (required), `returnUrl`, `configuration`, `locale` | Create a Stripe Billing Portal session | ## Example Queries [Section titled “Example Queries”](#example-queries) ### Fetch a customer with subscriptions and payment methods [Section titled “Fetch a customer with subscriptions and payment methods”](#fetch-a-customer-with-subscriptions-and-payment-methods) ```graphql query { stripe { customer(id: "cus_ABC123") { id name email subscriptions { data { id status items { data { price { unitAmount currency product { name } } } } } } paymentMethods(type: card) { data { id card { brand last4 expMonth expYear } } } } } } ``` ### List invoices for a customer [Section titled “List invoices for a customer”](#list-invoices-for-a-customer) ```graphql query { stripe { customer(id: "cus_ABC123") { invoices { data { id status amountDue amountPaid currency created hostedInvoiceUrl invoicePdf } } } } } ``` ### Create a billing portal session [Section titled “Create a billing portal session”](#create-a-billing-portal-session) ```graphql mutation { stripe { createBillingPortalSession( customer: "cus_ABC123" returnUrl: "https://myapp.com/account" ) { url } } } ``` ## Authorization [Section titled “Authorization”](#authorization) By default, only admin requests (those with a valid admin secret header) are allowed. You can provide a custom `isAllowed` function to implement fine-grained access control: ```ts import { createNhostClient, withAdminSession, } from '@nhost/nhost-js'; import { Context, createStripeGraphQLServer } from '@nhost/stripe-graphql-js'; const nhost = createNhostClient({ subdomain: process.env['NHOST_SUBDOMAIN']!, region: process.env['NHOST_REGION']!, configure: [ withAdminSession({ adminSecret: process.env['NHOST_ADMIN_SECRET']!, }), ], }); const server = createStripeGraphQLServer({ isAllowed: async (stripeCustomerId: string, context: Context) => { const { isAdmin, userClaims } = context; // Admins can access any customer if (isAdmin) { return true; } // Otherwise, verify the user owns this Stripe customer. // For example, look up the mapping in your database: const userId = userClaims?.['x-hasura-user-id']; if (!userId) { return false; } // Query your database to check if this user owns the Stripe customer const resp = await nhost.graphql.request({ query: ` query ($userId: uuid!, $stripeCustomerId: String!) { users(where: { id: { _eq: $userId }, metadata: { _contains: { stripeCustomerId: $stripeCustomerId } } }) { id } } `, variables: { userId, stripeCustomerId }, }); return (resp.body.data?.users?.length ?? 0) > 0; }, }); export default server; ``` The `isAllowed` function receives: * **`stripeCustomerId`**: The Stripe customer ID being accessed * **`context`**: An object containing: * `isAdmin` — Whether the request has admin privileges * `userClaims` — The decoded [JWT claims](/products/auth/jwt) (includes `x-hasura-user-id`, `x-hasura-default-role`, `x-hasura-allowed-roles`). The function is called for customer-scoped queries and mutations. Admin-only queries like `connectedAccounts` check `isAdmin` directly. ## Configuration [Section titled “Configuration”](#configuration) The `createStripeGraphQLServer` function accepts these options: | Option | Type | Default | Description | | -------------- | ------------------------------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | | `isAllowed` | `(stripeCustomerId, context) => boolean \| Promise