Quiltt Logo

Authentication

Link to this section#A Complete Guide to Authentication with Quiltt

Robust authentication is the cornerstone of secure and user-friendly applications. Whether you're building a fintech solution, a personal finance app, or any platform that requires user data, implementing a rock-solid authentication system is crucial. That's where Quiltt comes in.

In this comprehensive guide, we'll dive deep into authentication with Quiltt, exploring how to leverage the Auth API to obtain session tokens and implement secure authentication in your Next.js application.

While this tutorial uses Next.js, the core authentication concepts and API interactions remain the same regardless of your chosen frontend framework (like React, Vue, or Angular) or backend technology (like Express, Django, or Ruby on Rails). By the end of this post, you'll have a thorough understanding of Quiltt's authentication mechanisms and be well-equipped to create secure, seamless user experiences.

Link to this section#The Basics of Quiltt Authentication

Before we delve into the technical details, let's establish a foundational understanding of Quiltt's authentication system.

Quiltt provides a powerful Auth API that serves as the gateway to secure user authentication, with two different modes of use:

  1. Client-Side Sessions: For user-facing applications using session tokens
  2. Server-Side Access: For backend services using API keys

The Auth API allows you to manage Client-Side sessions via:

  1. Issuing new tokens
  2. Verifying that tokens haven't been revoked
  3. Revoking tokens when needed

The cornerstone of Quiltt authentication is the Session token. This token is your secret to launching the Quiltt Connector for specific user profiles making client-side GraphQL requests. 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.

Link to this section#Understanding Quiltt's Authentication Flow

Quiltt uses a secure two-step authentication process:

  1. Identification: First, the user provides their email. The API validates this and may trigger MFA.
  2. Authentication: If MFA is required, the user provides a passcode to complete authentication.

Each step returns appropriate status codes:

  • Identify: 201 (Created), 202 (MFA Required), 422 (Invalid Input)
  • Authenticate: 201 (Created), 401 (Unauthorized), 422 (Invalid Input)

Link to this section#Understanding Session Tokens

When issuing a Session token via the Auth API, you'll make a POST request to /v1/users/sessions. A successful request returns:

Let's break down this response:

  • token: The Session token itself
  • userId: The Quiltt Profile ID associated with this session
  • userUUID: A unique identifier for the user (your supplied UUID if provided)
  • environmentId: The ID of the Quiltt environment this session is associated with
  • expiration: The expiration time in Unix timestamp format
  • expiresAt: The expiration time in ISO 8601 format

Link to this section#Session Management

Quiltt's useQuilttSession hook provides several key functions for managing authentication state:

  1. session: The current session information (if authenticated)
  2. importSession: Import and validate a session token
  3. identifySession: Start the authentication process
  4. authenticateSession: Complete MFA verification
  5. revokeSession: Log out and invalidate the session
  6. forgetSession: Clear the local session state

Link to this section#Getting Started: Prerequisites

Before you can harness the power of Quiltt's Auth API, there are crucial prerequisites:

  1. Setting up an API Key:
    • Log in to the Quiltt Dashboard
    • Navigate to the API Keys section
    • Generate a new API Key for your application

Remember, your API Key's Secret is sensitive information. Always keep it secure and never expose it in client-side code or public repositories.

  1. Development Environment:
    • Node.js installed
    • Next.js knowledge
    • TypeScript familiarity
    • pnpm (recommended package manager)

Link to this section#Project Setup

First, create a new Next.js project with required dependencies:

Configure your environment variables:

Link to this section#Client-Side Authentication

First, let's set up the Quiltt provider to handle authentication state throughout your application.

Link to this section#Provider Setup

Add it to your root layout:

Link to this section#Login Implementation

Create a client-side login component that handles user authentication:

Link to this section#Protected Client Routes

For client-side protected routes, use the useQuilttSession hook:

Then add a logout implementation:

Link to this section#Server-Side Authentication

Let's create secure server-side components and routes to handle authentication.

Link to this section#API Routes

Create an authentication endpoint to handle login requests:

Link to this section#Server Components

Create server components that handle authentication and data fetching:

Link to this section#Server Actions

Implement server actions for secure form handling:

Link to this section#Route Protection

Protect routes using Next.js middleware:

Link to this section#Security Utilities

Link to this section#Token Validation

Create a utility for token validation:

Link to this section#Server-Side GraphQL Client

Create a secure GraphQL client for server-side requests:

Link to this section#Advanced Topics

As you become more comfortable with Quiltt authentication, you might want to explore more advanced topics:

  1. Multi-factor Authentication: While not natively supported by Quiltt, you can implement your own MFA system on top of Quiltt's authentication.

  2. OAuth Integration: If you're integrating with third-party services, you might need to implement OAuth flows alongside Quiltt authentication.

  3. Federated Identity: Consider how Quiltt authentication can work alongside other identity providers in your ecosystem.

Link to this section#Best Practices

  1. Use HTTP-only cookies for token storage
  2. Implement token refresh mechanism
  3. Validate tokens server-side before rendering protected pages
  4. Use Server Components for data fetching where possible
  5. Handle errors gracefully with proper status codes
  6. Implement proper CORS headers in middleware
  7. Follow Next.js security headers recommendations

Link to this section#Troubleshooting Common Issues

Even with a well-implemented authentication system, issues can arise. Here are some common problems and their solutions:

  1. "Invalid token" errors: Usually caused by expired tokens. Implement a token refresh mechanism.
  2. CORS issues: Ensure your server is configured to accept requests from your client's domain.
  3. Rate limiting: Be aware of Quiltt's rate limits and implement appropriate backoff strategies.
  4. Token storage issues: If tokens seem to disappear unexpectedly on the client side, review your storage method and consider server-side sessions.

Link to this section#Moving Forward with Quiltt Authentication

Authentication is a critical component of any modern application, and Quiltt provides a robust, flexible system to meet your needs. By leveraging the Auth API to obtain and manage Session tokens, and implementing best practices in both client-side and server-side code, you can create a secure, seamless authentication experience for your users.

Remember, authentication is an ongoing process. Stay informed about the latest security best practices, keep your dependencies updated, and regularly review and refine your authentication implementation.

With this guide, you're well-equipped to implement and manage authentication in your Quiltt-powered Next.js application. Happy coding, and here's to building secure, user-friendly applications!

Connectors →