Authentication
Link to this section#Mastering Quiltt Authentication
In this tutorial, we'll dive into authenticating end-users with Quiltt using the Quiltt Auth API. We'll learn how to obtain session tokens, launch Connector and fetch data from Quiltt's GraphQL API.
While this tutorial uses Next.js, the core concepts and API interactions remain for your chosen frontend framework (like React, Vue, or Angular) or backend technology (like Ruby on Rails, Django, Express, etc).
By the end of this tutorial, you'll have a thorough understanding of Quiltt's authentication mechanisms and be well-equipped to create secure Quiltt-powered financial experiences.
Link to this section#The Basics
A key concept to understand is the Session token, which allows you to launch the Quiltt Connector for a specific user, and to fetch data for them from the GraphQL API.
While there are several ways to authenticate with Quiltt, the Session token is the most flexible tool in a Quiltt builder's toolbox, as it allows your users to interact with the Quiltt Connector and for your app to interact with the Quiltt APIs, without needing to use passwords, secrets, or other sensitive credentials.
One of the great advantages of Quiltt's Session tokens is that, when handled correctly, they can be safely used in client-side code, offering flexibility in your application architecture and reducing the amount of server-side code you need to write and maintain.
Link to this section#Understanding Session Tokens
Issuing a Session token requires making an API request to:
POSThttps://api.quiltt.io/v1/users/session
A successful request returns:
The most important part of this response is the token
field. We'll use this to authenticate to securely launch the Quiltt Connector for the user, and interact with their data via the GraphQL API.
Link to this section#Managing Sessions in React
The Quiltt React SDK provides hooks and components to help you manage sessions in your React application.
The useQuilttSession
hook provides several key functions for managing authentication state:
session
: The current session information (if authenticated)importSession
: Import and validate a session for use in client-side coderevokeSession
: Log out and invalidate the sessionforgetSession
: Clear the local session state
While you're welcome to use this hook directly, in this tutorial we'll use the handy QuilttProvider
React component to automatically import a session for us after we obtain it from the Quiltt Auth API.
Link to this section#Prerequisites
Before proceeding, you'll need to ensure that you have:
- A Quiltt Dashboard account.
- A recent version of Node.js installed on your machine.
- A package manager like
pnpm
,yarn
ornpm
. The examples in this tutorial usepnpm
.
Link to this section#Project Setup
First, let's create a new Next.js project with required dependencies:
Next, add your Quiltt API Key Secret and Quiltt Connector ID to your environment variables. You can find these in the API Keys section and the Connector sections of the Quiltt Dashboard, respectively.
Remember, your API Key's Secret is sensitive and should always be kept out of client-side code and source control systems like Git.
Finally, launch the development server and open http://localhost:3000 in your browser:
Link to this section#Get a Session Token from the server
Now let's securely obtain a session token from the Auth API. We'll use a Next.js Route Handler to ensure this sensitive operation is performed server-side:
Next, we'll fetch this token from the client and pass it to <QuilttProvider>
, making it available to the rest of the app.
Link to this section#Wire up the Provider to your layout
Now, let's add the Providers
component to our layout, so its children have access to the Session.
For this example, we'll add our Providers
component to the root layout, but in a real app you'll likely want to do this in a more deeply-nested layout that's shown to an authenticated user. This will allow you to obtain the Session token for that specific user.
Link to this section#Add a Button to launch the Connector
Next, we'll add a button letting your user launch the Connector we specified in our Environment variables. This Connector will automatically authenticate the user from the Session token we passed to QuilttProvider
.
Now when you navigate to http://localhost:3000, you can click the "Launch Connector" button to launch the Connector for the authenticated user:
See the Quiltt React SDK documentation for more information on how to customize the Connector, set up callback listeners, and more.
Link to this section#Fetch data from GraphQL
Now that we have the basic authentication flow wired up, let's make our first GraphQL call to fetch data for the end-user.
There are many ways to call the Quiltt GraphQL API. For now, we'll roll our own simple GraphQL client.
Now let's create a simple client-side component that will greet our user by fetching their data from GraphQL, using the Session token we obtained earlier.
Finally, let's wrap things up by adding our new Welcome
component to our Home
page
Now refresh the page and you'll see a simple greeting with the user's email or ID, right above the Connector launcher.
Link to this section#Conclusion
In this tutorial, we've covered the basics of authenticating users with Quiltt, from obtaining a Session token to launching a Connector and fetching data from GraphQL.
Armed with this knowledge, you're well-equipped to build secure and user-friendly financial applications with Quiltt.
Please refer to the Quiltt Authentication and the Quiltt React SDK guides for more detailed information on authentication and how to use Quiltt in your React application.