0
# Authentication & Authorization
1

2
Complete authentication system with login, logout, registration flows, and fine-grained access control for resources and actions.
3

4
## Capabilities
5

6
### Authentication Hooks
7

8
#### useLogin Hook
9

10
Handles user login operations with credential validation and session management.
11

12
```typescript { .api }
13
/**
14
 * Handles user login operations
15
 * @param params - Configuration for login mutation
16
 * @returns Login mutation function and state
17
 */
18
function useLogin<TData = {}, TError = {}, TVariables = {}>(
19
  params?: UseLoginConfig<TData, TError, TVariables>
20
): UseLoginReturnType<TData, TError, TVariables>;
21

22
interface UseLoginConfig<TData, TError, TVariables> {
23
  /** React Query mutation options */
24
  mutationOptions?: UseMutationOptions<TData, TError, TVariables>;
25
}
26

27
interface UseLoginReturnType<TData, TError, TVariables> {
28
  /** Login mutation function */
29
  mutate: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => void;
30
  /** Async login mutation function */
31
  mutateAsync: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => Promise<TData>;
32
  /** React Query mutation result */
33
  mutation: UseMutationResult<TData, TError, TVariables>;
34
}
35
```
36

37
**Usage Example:**
38

39
```typescript
40
import { useLogin } from "@refinedev/core";
41

42
function LoginForm() {
43
  const { mutate: login, isLoading } = useLogin<
44
    { success: boolean },
45
    { message: string },
46
    { email: string; password: string }
47
  >();
48
  
49
  const handleSubmit = (credentials: { email: string; password: string }) => {
50
    login(credentials, {
51
      onSuccess: (data) => {
52
        console.log("Login successful:", data);
53
      },
54
      onError: (error) => {
55
        console.error("Login failed:", error.message);
56
      }
57
    });
58
  };
59
  
60
  return (
61
    <form onSubmit={handleSubmit}>
62
      <input name="email" type="email" placeholder="Email" />
63
      <input name="password" type="password" placeholder="Password" />
64
      <button type="submit" disabled={isLoading}>
65
        {isLoading ? "Logging in..." : "Login"}
66
      </button>
67
    </form>
68
  );
69
}
70
```
71

72
#### useLogout Hook
73

74
Handles user logout operations and session cleanup.
75

76
```typescript { .api }
77
/**
78
 * Handles user logout operations
79
 * @param params - Configuration for logout mutation
80
 * @returns Logout mutation function and state
81
 */
82
function useLogout<TData = {}, TError = {}, TVariables = {}>(
83
  params?: UseLogoutConfig<TData, TError, TVariables>
84
): UseLogoutReturnType<TData, TError, TVariables>;
85

86
interface UseLogoutConfig<TData, TError, TVariables> {
87
  /** React Query mutation options */
88
  mutationOptions?: UseMutationOptions<TData, TError, TVariables>;
89
}
90

91
interface UseLogoutReturnType<TData, TError, TVariables> {
92
  /** Logout mutation function */
93
  mutate: (variables?: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => void;
94
  /** Async logout mutation function */
95
  mutateAsync: (variables?: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => Promise<TData>;
96
  /** React Query mutation result */
97
  mutation: UseMutationResult<TData, TError, TVariables>;
98
}
99
```
100

101
#### useRegister Hook
102

103
Handles user registration with validation and automatic login.
104

105
```typescript { .api }
106
/**
107
 * Handles user registration
108
 * @param params - Configuration for registration mutation
109
 * @returns Registration mutation function and state
110
 */
111
function useRegister<TData = {}, TError = {}, TVariables = {}>(
112
  params?: UseRegisterConfig<TData, TError, TVariables>
113
): UseRegisterReturnType<TData, TError, TVariables>;
114

115
interface UseRegisterConfig<TData, TError, TVariables> {
116
  /** React Query mutation options */
117
  mutationOptions?: UseMutationOptions<TData, TError, TVariables>;
118
}
119

120
interface UseRegisterReturnType<TData, TError, TVariables> {
121
  /** Registration mutation function */
122
  mutate: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => void;
123
  /** Async registration mutation function */
124
  mutateAsync: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => Promise<TData>;
125
  /** React Query mutation result */
126
  mutation: UseMutationResult<TData, TError, TVariables>;
127
}
128
```
129

130
#### useIsAuthenticated Hook
131

132
Checks current authentication status and manages authentication state.
133

134
```typescript { .api }
135
/**
136
 * Checks if user is authenticated
137
 * @param params - Configuration for authentication check
138
 * @returns Authentication status query result
139
 */
140
function useIsAuthenticated<TData = {}>(
141
  params?: UseIsAuthenticatedConfig<TData>
142
): UseIsAuthenticatedReturnType<TData>;
143

144
interface UseIsAuthenticatedConfig<TData> {
145
  /** Additional parameters for auth check */
146
  params?: any;
147
  /** React Query options */
148
  queryOptions?: UseQueryOptions<TData>;
149
}
150

151
interface UseIsAuthenticatedReturnType<TData> {
152
  /** Query result with authentication status */
153
  query: UseQueryResult<TData>;
154
  /** Authentication check result */
155
  data: CheckResponse | undefined;
156
  /** Whether the check is loading */
157
  isLoading: boolean;
158
  /** Whether the check has error */
159
  isError: boolean;
160
  /** Error if authentication check failed */
161
  error: unknown;
162
}
163

164
interface CheckResponse {
165
  /** Whether user is authenticated */
166
  authenticated: boolean;
167
  /** Redirect URL if not authenticated */
168
  redirectTo?: string;
169
  /** Whether to show logout button */
170
  logout?: boolean;
171
  /** Error information */
172
  error?: Error;
173
}
174
```
175

176
**Usage Example:**
177

178
```typescript
179
import { useIsAuthenticated } from "@refinedev/core";
180

181
function AuthChecker() {
182
  const { data: authData, isLoading } = useIsAuthenticated();
183
  
184
  if (isLoading) {
185
    return <div>Checking authentication...</div>;
186
  }
187
  
188
  if (authData?.authenticated) {
189
    return <div>User is logged in</div>;
190
  }
191
  
192
  return <div>User needs to login</div>;
193
}
194
```
195

196
#### useGetIdentity Hook
197

198
Retrieves current user identity and profile information.
199

200
```typescript { .api }
201
/**
202
 * Gets current user identity/profile
203
 * @param params - Configuration for identity query
204
 * @returns User identity query result
205
 */
206
function useGetIdentity<TData = {}>(
207
  params?: UseGetIdentityConfig<TData>
208
): UseGetIdentityReturnType<TData>;
209

210
interface UseGetIdentityConfig<TData> {
211
  /** React Query options */
212
  queryOptions?: UseQueryOptions<TData>;
213
}
214

215
interface UseGetIdentityReturnType<TData> {
216
  /** Query result with user identity */
217
  query: UseQueryResult<TData>;
218
  /** User identity data */
219
  data: TData | undefined;
220
}
221
```
222

223
#### usePermissions Hook
224

225
Retrieves user permissions for access control decisions.
226

227
```typescript { .api }
228
/**
229
 * Gets user permissions
230
 * @param params - Configuration for permissions query
231
 * @returns User permissions query result
232
 */
233
function usePermissions<TData = any>(
234
  params?: UsePermissionsConfig<TData>
235
): UsePermissionsReturnType<TData>;
236

237
interface UsePermissionsConfig<TData> {
238
  /** Additional parameters for permission check */
239
  params?: any;
240
  /** React Query options */
241
  queryOptions?: UseQueryOptions<TData>;
242
}
243

244
interface UsePermissionsReturnType<TData> {
245
  /** Query result with permissions */
246
  query: UseQueryResult<TData>;
247
  /** Permissions data */
248
  data: TData | undefined;
249
}
250
```
251

252
### Password Management
253

254
#### useForgotPassword Hook
255

256
Handles forgot password flow with email verification.
257

258
```typescript { .api }
259
/**
260
 * Handles forgot password flow
261
 * @param params - Configuration for forgot password mutation
262
 * @returns Forgot password mutation function and state
263
 */
264
function useForgotPassword<TData = {}, TError = {}, TVariables = {}>(
265
  params?: UseForgotPasswordConfig<TData, TError, TVariables>
266
): UseForgotPasswordReturnType<TData, TError, TVariables>;
267

268
interface UseForgotPasswordConfig<TData, TError, TVariables> {
269
  /** React Query mutation options */
270
  mutationOptions?: UseMutationOptions<TData, TError, TVariables>;
271
}
272

273
interface UseForgotPasswordReturnType<TData, TError, TVariables> {
274
  /** Forgot password mutation function */
275
  mutate: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => void;
276
  /** Async forgot password mutation function */
277
  mutateAsync: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => Promise<TData>;
278
  /** React Query mutation result */
279
  mutation: UseMutationResult<TData, TError, TVariables>;
280
}
281
```
282

283
#### useUpdatePassword Hook
284

285
Handles password update operations with validation.
286

287
```typescript { .api }
288
/**
289
 * Handles password update
290
 * @param params - Configuration for password update mutation
291
 * @returns Password update mutation function and state
292
 */
293
function useUpdatePassword<TData = {}, TError = {}, TVariables = {}>(
294
  params?: UseUpdatePasswordConfig<TData, TError, TVariables>
295
): UseUpdatePasswordReturnType<TData, TError, TVariables>;
296

297
interface UseUpdatePasswordConfig<TData, TError, TVariables> {
298
  /** React Query mutation options */
299
  mutationOptions?: UseMutationOptions<TData, TError, TVariables>;
300
}
301

302
interface UseUpdatePasswordReturnType<TData, TError, TVariables> {
303
  /** Password update mutation function */
304
  mutate: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => void;
305
  /** Async password update mutation function */
306
  mutateAsync: (variables: TVariables, options?: MutationObserverOptions<TData, TError, TVariables>) => Promise<TData>;
307
  /** React Query mutation result */
308
  mutation: UseMutationResult<TData, TError, TVariables>;
309
}
310
```
311

312
### Error Handling
313

314
#### useOnError Hook
315

316
Handles authentication-related errors and automatic logout on token expiration.
317

318
```typescript { .api }
319
/**
320
 * Handles authentication errors
321
 * @param params - Configuration for error handling
322
 * @returns Error handling mutation
323
 */
324
function useOnError(params?: UseOnErrorConfig): UseOnErrorReturnType;
325

326
interface UseOnErrorConfig {
327
  /** React Query mutation options */
328
  mutationOptions?: UseMutationOptions<OnErrorResponse, Error, any>;
329
}
330

331
interface UseOnErrorReturnType {
332
  /** Error handling mutation function */
333
  mutate: (error: any) => void;
334
  /** Async error handling function */
335
  mutateAsync: (error: any) => Promise<OnErrorResponse>;
336
  /** Mutation result */
337
  mutation: UseMutationResult<OnErrorResponse, Error, any>;
338
}
339

340
interface OnErrorResponse {
341
  /** Whether to redirect user */
342
  redirectTo?: string;
343
  /** Whether to logout user */
344
  logout?: boolean;
345
  /** Error message to display */
346
  error?: Error;
347
}
348
```
349

350
### Access Control
351

352
#### useCan Hook
353

354
Checks permissions for specific resources and actions with role-based access control.
355

356
```typescript { .api }
357
/**
358
 * Checks permissions for actions on resources
359
 * @param params - Permission check configuration
360
 * @returns Permission check query result
361
 */
362
function useCan(params: UseCanConfig): UseCanReturnType;
363

364
interface UseCanConfig {
365
  /** Resource name to check permissions for */
366
  resource?: string;
367
  /** Action to check permissions for */
368
  action: string;
369
  /** Additional parameters for permission check */
370
  params?: CanParams;
371
  /** React Query options */
372
  queryOptions?: UseQueryOptions<CanReturnType>;
373
}
374

375
interface UseCanReturnType {
376
  /** Query result with permission status */
377
  query: UseQueryResult<CanReturnType>;
378
  /** Permission check result */
379
  data: CanReturnType | undefined;
380
}
381

382
interface CanReturnType {
383
  /** Whether access is granted */
384
  can: boolean;
385
  /** Reason for denial if access not granted */
386
  reason?: string;
387
}
388

389
interface CanParams {
390
  /** Resource being accessed */
391
  resource?: string;
392
  /** Action being performed */
393
  action?: string;
394
  /** Record ID being accessed */
395
  id?: BaseKey;
396
  /** Additional context data */
397
  [key: string]: any;
398
}
399
```
400

401
**Usage Example:**
402

403
```typescript
404
import { useCan } from "@refinedev/core";
405

406
function PostActions({ postId }: { postId: string }) {
407
  const { data: canEdit } = useCan({
408
    resource: "posts",
409
    action: "edit",
410
    params: { id: postId }
411
  });
412
  
413
  const { data: canDelete } = useCan({
414
    resource: "posts", 
415
    action: "delete",
416
    params: { id: postId }
417
  });
418
  
419
  return (
420
    <div>
421
      {canEdit?.can && (
422
        <button>Edit Post</button>
423
      )}
424
      {canDelete?.can && (
425
        <button>Delete Post</button>
426
      )}
427
      {!canEdit?.can && canEdit?.reason && (
428
        <p>Cannot edit: {canEdit.reason}</p>
429
      )}
430
    </div>
431
  );
432
}
433
```
434

435
### Authentication Providers
436

437
#### useAuthenticated Hook
438

439
Higher-level authentication check with automatic redirects and loading states.
440

441
```typescript { .api }
442
/**
443
 * Higher-level authentication check with redirects
444
 * @param params - Authentication check configuration
445
 * @returns Authentication check result with redirect handling
446
 */
447
function useAuthenticated(params?: UseAuthenticatedConfig): UseAuthenticatedReturnType;
448

449
interface UseAuthenticatedConfig {
450
  /** Parameters for authentication check */
451
  params?: any;
452
  /** Where to redirect on authentication failure */
453
  redirectOnFail?: string;
454
  /** Whether to append current path to redirect URL */
455
  appendCurrentPathToQuery?: boolean;
456
}
457

458
interface UseAuthenticatedReturnType {
459
  /** Whether user is authenticated */
460
  isLoading: boolean;
461
  /** Authentication error if any */
462
  error: any;
463
  /** Authentication check data */
464
  data: CheckResponse | undefined;
465
}
466
```
467

468
## Types
469

470
```typescript { .api }
471
interface AuthProvider {
472
  /** Login function */
473
  login: (params: any) => Promise<AuthActionResponse>;
474
  /** Logout function */
475
  logout: (params: any) => Promise<AuthActionResponse>;
476
  /** Check authentication status */
477
  check: (params?: any) => Promise<CheckResponse>;
478
  /** Handle authentication errors */
479
  onError: (error: any) => Promise<OnErrorResponse>;
480
  /** Register new user */
481
  register?: (params: any) => Promise<AuthActionResponse>;
482
  /** Forgot password flow */
483
  forgotPassword?: (params: any) => Promise<AuthActionResponse>;
484
  /** Update password */
485
  updatePassword?: (params: any) => Promise<AuthActionResponse>;
486
  /** Get user permissions */
487
  getPermissions?: (params?: any) => Promise<any>;
488
  /** Get user identity */
489
  getIdentity?: (params?: any) => Promise<any>;
490
}
491

492
interface AuthActionResponse {
493
  /** Whether the action was successful */
494
  success: boolean;
495
  /** Redirect URL after action */
496
  redirectTo?: string;
497
  /** Error information if failed */
498
  error?: Error;
499
}
500

501
interface IdentityResponse {
502
  /** User ID */
503
  id: BaseKey;
504
  /** User name or display name */
505
  name: string;
506
  /** User email */
507
  email?: string;
508
  /** User avatar/profile image URL */
509
  avatar?: string;
510
  /** Additional user properties */
511
  [key: string]: any;
512
}
513

514
interface PermissionResponse {
515
  /** Array of user permissions */
516
  permissions: string[];
517
  /** User roles */
518
  roles?: string[];
519
  /** Additional permission data */
520
  [key: string]: any;
521
}
522

523
interface AccessControlProvider {
524
  /** Check if user can perform action on resource */
525
  can: (params: CanParams) => Promise<CanReturnType>;
526
}
527

528
interface ValidationErrors {
529
  [field: string]: string | string[];
530
}
531
```