2. Create Auth Provider From Scratch

We will show you how to create an auth provider from scratch in this section. After you understand the logic of the auth provider, you can easily integrate third-party authentication services or custom auth providers. We will be using mock data to better focus on the auth provider.

Creating a Mock Auth Provider​

First, create a new file named authProvider.ts in the src folder and add the following code:

import type { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    login: async (params: any) => ({}),
    check: async (params: any) => ({}),
    logout: async (params: any) => ({}),
    onError: async (params: any) => ({}),
};

export default authProvider;

Now, to pass the authProvider to the <Refine/> component, open App.tsx file and add the related code:

// ---
import authProvider from "./authProvider";

<Refine
    // ---
    authProvider={authProvider}
/>;

Our mock auth provider is now up and running with all the required methods, but they don't do anything yet. We will now add logic to these methods.

Required Methods​

login​

login method is used to authenticate users. It expects to return a resolved promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

• success: Determines whether the operation is successful or not.
• redirectTo: The path of the page that the user will be redirected to after the operation is completed.
• error: An object containing details about any errors encountered during the operation.
• [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

We will use a mock user list and check if the user exists in the list. If they do, we will save the user data to the local storage and resolve the promise with success: true. Otherwise, we will resolve the promise with success: false:

import { AuthBindings } from "@refinedev/core";

const mockUsers = [{ email: "john@mail.com" }, { email: "jane@mail.com" }];

const authProvider: AuthBindings = {
    login: async ({ email, password }) => {
        // Suppose we actually send a request to the back end here.
        const user = mockUsers.find((item) => item.email === email);

        if (user) {
            localStorage.setItem("auth", JSON.stringify(user));
            return {
                success: true,
                redirectTo: "/",
            };
        }

        return {
            success: false,
            error: {
                message: "Login Error",
                name: "Invalid email or password",
            },
        };
    },
    // ---
};

Invoking the useLogin hook's mutation will call the login method, passing in the mutation's parameters as arguments. This means the parameters for the useLogin hook's mutation must match the parameters of the login method.

For example, if we call the useLogin hook's mutation like this:

import { useLogin } from "@refinedev/core";

const { mutate } = useLogin();

mutate({ email: "john@mail.com", password: "123456" });

The login method will get the mutation's parameters as arguments.

At this point, we can authenticate users but can't check if the user is authenticated or not when the user refreshes the page or navigates to another page. We will add the logic to the check method to solve this problem.

const { mutate } = useLogin<{
    username: string;
    password: string;
    foo: string;
    remember: boolean;
}>();

const authProvider: AuthBindings = {
    // ---
    login: async () => {
        // ---
        if (user) {
            return {
                success: true,
                redirectTo: "/custom-page",
            };
        } else {
            return {
                success: false,
                redirectTo: "/register",
            };
        }
    },
};

const { mutate } = useLogin();

mutate({ redirectPath: "/custom-page" });

const authProvider: AuthBindings = {
    // ---
    login: async ({ redirectPath }) => {
        //---
        return {
            success: false,
            redirectTo: redirectPath,
        };
    },
};

const authProvider: AuthBindings = {
    // ---
    login: async () => {
        // ---
        return {
            success: false,
            redirectTo: undefined,
        };
    },
};

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    login: async ({ email, password }) => {
        // ---
        return {
            success: false,
            error: {
                name: "Login Failed!",
                message:
                    "The email or password that you've entered doesn't match any account.",
            },
        };
    },
    // ---
};

For more information, refer to the useLogin documentation→

check​

The check method is used to check if the user is authenticated. It is internally called when the user navigates to a page that requires authentication. This method expects to return a resolved promise with the following type:

type CheckResponse = {
    authenticated: boolean;
    redirectTo?: string;
    logout?: boolean;
    error?: Error;
};

• authenticated: A boolean value indicating whether the user is authenticated or not.
• redirectTo: A string value indicating the URL to redirect to if authentication is required.
• logout: A boolean value indicating whether the user should be logged out.
• error: An Error object representing any errors that may have occurred during the check.

Since we saved the user data to the local storage, we will check that to determine if the user is authenticated:

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // ---
    check: async () => {
        const user = localStorage.getItem("auth");

        if (user) {
            return {
                authenticated: true,
            };
        }

        return {
            authenticated: false,
            logout: true,
            redirectTo: "/login",
            error: {
                message: "Check failed",
                name: "Unauthorized",
            },
        };
    },
    // ---
};

Invoking the useIsAuthenticated hook will call the check method. If check method resolves a data, it will be available in the useIsAuthenticated hook's data property.

import { useIsAuthenticated } from "@refinedev/core";

const { data, isSuccess, isLoading, isError, refetch } = useIsAuthenticated();

const authProvider: AuthBindings = {
    // ---
    check: async () => {
        // ---
        return {
            authenticated: false,
            redirectTo: "/custom-page",
        };
    },
};

For more information, refer to the useIsAuthenticated documentation→

logout​

The logout method is used to log out users. It expects to return a resolved promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

• success: Determines whether the operation is successful or not.
• redirectTo: The path of the page that the user will be redirected to after the operation is completed.
• error: An object containing details about any errors encountered during the operation.
• [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

Opposite to what we did in the login method, we now need to remove the user data from the local storage upon log out:

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // ---
    logout: async () => {
        localStorage.removeItem("auth");
        return {
            success: true,
            redirectTo: "/login",
        };
    },
    // ---
};

Invoking the useLogout hook's mutation will call the logout method. If you need to pass any parameters to the logout method, you can use the useLogout hook's mutation.

For example, if we call the useLogout hook's mutation like this:

import { useLogout } from "@refinedev/core";

const { mutate } = useLogout();

mutate({ id: "1" });

The logout method will get the mutation's parameters as an argument.

const { mutate } = useLogout<{
    id: string;
    name: string;
}>();

const authProvider: AuthBindings = {
    // ---
    logout: async () => {
        // ---
        return {
            success: true,
            redirectTo: "/login",
        };
    },
};

const { mutate } = useLogout();

mutate({ redirectPath: "/custom-page" });

const authProvider: AuthBindings = {
    // ---
    logout: ({ redirectPath }) => {
        // ---
        return {
            success: true,
            redirectTo: redirectPath,
        };
    },
};

const authProvider: AuthBindings = {
    // ---
    logout: async () => {
        // ---
        return {
            success: true,
            redirectTo: undefined,
        };
    },
};

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    logout: async () => {
        // ---
        return {
            success: false,
            error: {
                name: "Logout Failed!",
                message: "Something went wrong.",
            },
        };
    },
    // ---
};

For more information, refer to the useLogout documentation→

onError​

onError method is called when you get an error response from the API. You can create your own business logic to handle the error such as refreshing the token, logging out the user, etc.

onError method expects to return a Promise with the following type:

type OnErrorResponse = {
    redirectTo?: string;
    logout?: boolean;
    error?: Error;
};

• redirectTo: If has a value, the app will be redirected to the given URL.
• logout: If is true, useOnError calls the logout method.
• error: An Error object representing any errors that may have occurred during the operation.

We'll use the onError method to log out the user if the API returns a 401 or 403 error. If redirectTo is set, logout method will be called with the redirectTo value.

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // ---
    onError: async (error) => {
        if (error.status === 401 || error.status === 403) {
            return {
                logout: true,
                redirectTo: "/login",
                error,
            };
        }

        return {};
    },
    // ---
};

Invoking the useOnError hook's mutation will call the onError method, passing in the mutation's parameters as arguments.

For example, if you want to check the error of a fetch request, you can use the useOnError hook's mutation like this:

import { useOnError } from "@refinedev/core";

const { mutate } = useOnError();

fetch("http://example.com/payment")
    .then(() => console.log("Success"))
    .catch((error) => mutate(error));

const authProvider: AuthBindings = {
    // ---
    onError: async (error) => {
        if (error.status === 401 || error.status === 403) {
            return {
                redirectTo: "/custom-page",
            };
        }

        return {};
    },
    // ---
};

For more information, refer to the useOnError documentation→

Optional Methods​

getPermissions​

getPermissions method is used to get the user's permissions. It expects to return a resolved promise.

We will use the getPermissions method to get the user's permissions from the localStorage.

import { AuthBindings } from "@refinedev/core";

const mockUsers = [
    { email: "john@mail.com", roles: ["admin"] },
    { email: "jane@mail.com", roles: ["editor"] },
];

const authProvider: AuthBindings = {
    // ---
    getPermissions: () => {
        const user = localStorage.getItem("auth");

        if (user) {
            const { roles } = JSON.parse(user);

            return roles;
        }

        return null;
    },
    // ---
};

Invoking the usePermissions hook will call the getPermissions method. If getPermissions method resolves a data, it will be available in the usePermissions hook's data property.

For example, if you want to check if the user has a specific permission, you can use the usePermissions hook like this:

import { usePermissions } from "@refinedev/core";

const { data } = usePermissions();

if (data?.includes("admin")) {
    console.log("User has admin permissions");
}

For more information, refer to the usePermissions documentation →

getIdentity​

getIdentity method is used to get the user's identity. It expects to return a resolved promise.

To get the user's identity from the local storage and resolve the promise:

import { AuthBindings } from "@refinedev/core";

const mockUsers = [
    { email: "john@mail.com", roles: ["admin"] },
    { email: "jane@mail.com", roles: ["editor"] },
];

const authProvider: AuthBindings = {
    // ---
    getIdentity: async () => {
        const user = localStorage.getItem("auth");

        if (user) {
            const { email, roles } = JSON.parse(user);

            return { email, roles };
        }

        return null;
    },
    // ---
};

Invoking the useGetIdentity hook will call the getIdentity method. If getIdentity method resolves a data, it will be available in the useGetIdentity hook's data property.

For example, if you want to get the user's email, you can use the useGetIdentity hook like this:

import { useGetIdentity } from "@refinedev/core";

const { data } = useGetIdentity();

if (data) {
    console.log(data.email);
}

const authProvider: AuthBindings = {
    // ---
    getIdentity: async () => {
        const user = localStorage.getItem("auth");

        if (user) {
            const { email, roles } = JSON.parse(user);

            return {
                email,
                roles,
                name: "John Doe",
                avatar: "https://i.pravatar.cc/300",
            };
        }

        return null;
    },
    // ---
};

For more information, refer to the useGetIdentity documentation→

register​

register method is used to register a new user. It is similar to the login method. It expects to return a resolved promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

• success: Determines whether the operation is successful or not.
• redirectTo: The path of the page that the user will be redirected to after the operation is completed.
• error: An object containing details about any errors encountered during the operation.
• [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

We'll register a new user and resolve the promise.

import { AuthBindings } from "@refinedev/core";

const mockUsers = [{ email: "john@mail.com" }, { email: "jane@mail.com" }];

const authProvider: AuthBindings = {
    // ---
    register: async ({ email }) => {
        const user = mockUsers.find((user) => user.email === email);

        if (user) {
            return {
                success: false,
                error: {
                    name: "Register Error",
                    message: "User already exists",
                },
            };
        }

        mockUsers.push({ email });

        return {
            success: true,
            redirectTo: "/login",
        };
    },
    // ---
};

Invoking the useRegister hook's mutation will call the register method, passing in the mutation's parameters as arguments.

For example, if you want to register a new user, you can use the useRegister hook like this:

import { useRegister } from "@refinedev/core";

const { mutate } = useRegister();

const handleRegister = (values) => {
    mutate(values);
};

The register method will get the mutation's parameters as arguments.

const { mutate } = useRegister<{
    username: string;
    email: string;
    password: string;
    confirmPassword: string;
    remember: boolean;
}>();

const authProvider: AuthBindings = {
    // ---
    register: async () => {
        // ---
        return {
            success: true, // or false
            redirectTo: "/custom-page",
        };
    },
};

const { mutate } = useRegister();

mutate({ redirectPath: "/custom-page" });

const authProvider: AuthBindings = {
    // ---
    register: async ({ redirectPath }) => {
        // ---
        return {
            success: true, // or false
            redirectTo: redirectPath,
        };
    },
};

const authProvider: AuthBindings = {
    // ---
    register: async () => {
        // ---
        return {
            success: true, // or false
            redirectTo: undefined,
        };
    },
};

const authProvider: AuthBindings = {
    // ---
    register: async () => {
        // ---
        return {
            success: false,
            error: {
                name: "Error",
                message: "Something went wrong!",
            },
        };
    },
};

For more information, refer to the useRegister documentation→

forgotPassword​

forgotPassword method is used to send a password reset link to the user's email address. It expects to return a resolved promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

• success: Determines whether the operation is successful or not.
• redirectTo: The path of the page that the user will be redirected to after the operation is completed.
• error: An object containing details about any errors encountered during the operation.
• [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

To send a password reset link to the user's email address and resolve the promise:

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // ---
    forgotPassword: async ({ email }) => {
        // send password reset link to the user's email address here

        // if request is successful
        return {
            success: true,
            redirectTo: "/login",
        };

        // if request is not successful
        return {
            success: false,
            error: {
                name: "Forgot Password Error",
                message: "Email address does not exist",
            },
        };
    },
    // ---
};

Invoking the useForgotPassword hook's mutation will call the forgotPassword method, passing in the mutation's parameters as arguments.

For example, if you want to send a password reset link to the user's email address, you can use the useForgotPassword hook like this:

import { useForgotPassword } from "@refinedev/core";

const { mutate } = useForgotPassword();

const handleForgotPassword = (values) => {
    mutate(values);
};

The forgotPassword method will get the mutation's parameters as arguments.

const { mutate } = useForgotPassword<{
    email: string;
}>();

const authProvider: AuthBindings = {
    // ---
    forgotPassword: async () => {
        // ---
        return {
            success: true,
            redirectTo: "/login",
        };
    },
};

const { mutate } = useForgotPassword();

useForgotPassword({ redirectPath: "/custom-page" });

const authProvider: AuthBindings = {
    // ---
    forgotPassword: async ({ redirectPath }) => {
        // ---
        return {
            success: true,
            redirectTo: redirectPath,
        };
    },
};

const authProvider: AuthBindings = {
    // ---
    forgotPassword: async () => {
        // ---
        return {
            success: false,
            error: {
                name: "Error",
                message: "Something went wrong!",
            },
        };
    },
};

For more information, refer to the useForgotPassword documentation →

updatePassword​

updatePassword method is used to update the user's password. It expects to return a resolved promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

• success: Determines whether the operation is successful or not.
• redirectTo: The path of the page that the user will be redirected to after the operation is completed.
• error: An object containing details about any errors encountered during the operation.
• [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

To update the user's password and resolve the promise:

import { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // ---
    updatePassword: async ({ password }) => {
        // update the user's password here

        // if request is successful
        return {
            success: true,
            redirectTo: "/login",
        };

        // if request is not successful
        return {
            success: false,
            error: {
                name: "Forgot Password Error",
                message: "Email address does not exist",
            },
        };
    },
    // ---
};