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 application. 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.

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
2. Server-Side Access

The Auth API allows you to mange Client-Side session via:

1. Issuing new tokens
2. Verifying that tokens haven’t been revoked
3. Revoke 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.

Getting Started: Prerequisites

Before you can harness the power of Quiltt's Auth API, there's a crucial prerequisite: setting up an API Key for your application.

To obtain your API secret:

1. Log in to the Quiltt Dashboard
2. Navigate to the API Keys section
3. 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.

This API Secret can later be used to access the GraphQL Profile API. In this guide, we'll start with client-side access to create a new profile. Once we've registered a user and created a profile, we'll cover how to access the profile's data using the server API secret.

Diving In: Using the Auth API to Obtain Session Tokens

Now that we have our API secret, let's explore how to use the Auth API to obtain session tokens.

Creating a Profile And Issuing a Session Token

To issue a Session token, you'll need to make a POST request to the /v1/users/sessions endpoint. Here's a step-by-step breakdown:

1. Endpoint: POST <https://auth.quiltt.io/v1/users/sessions>
2. Headers:

Authorization: Bearer YOUR_API_KEY_SECRET
Content-Type: application/json
Accept: application/json

Request body:

{ // Note: All fields are optional on the inital request 
  // Adding extra data may help with debugging via the Quiltt Dashboard.
  "userId": "UUID" // You may import a UUID from your system if you want referential matching
  "email": "example@quiltt.dev"
  "phone": "+12223334444"
  "name": "Jane Smith"
}

‍

If your request is successful, you'll receive a response that looks something like this:

{
  "token": "eyJhbGciOiJIUzUxMiJ9...",
  "userId": "p_Wl7Q1gRLrtmt1XKxTXf3WW"
  "userUUID": "0192f733-2942-78f9-9e24-1622f4769ad8",
  "expiration": 1672288186,
  "expiresAt": "2023-09-29T13:31:59Z",
  "environmentId": "env_Kx1gRL7Qfrtmt1XTXWl3WW"
}

‍

The token field in this response contains your Session token. This is what you'll use for subsequent API calls to authenticate your requests.

Understanding the Response

Let's break down the response:

• token: The Session token itself.
• userId: The Quiltt Profile ID associated with this session.
• userUuid: A unique identifier for the user. This will be your own supplied UUID if you provided one.
• environmentId: The ID of the Quiltt environment this session is associated with.
• expiration: The expiration time of the token in Unix timestamp format.
• expiresAt: The expiration time in a human-readable ISO 8601 format.

‍

Authenticating Existing Profiles

The Auth API is flexible enough to handle both existing users and new sign-ups. For exiting users Simply provide their Profile ID or UUID in the userId field of your request. You may also update any additional Profile attributes while issuing the token. For example:

{
  "userId": "p_Wl7Q1gRLrtmt1XKxTXf3WW", // May be either the userId or userUUID
  "metadata": {
    "favoriteColor": "blue"
  }
}

‍

This flexibility allows you to seamlessly integrate Quiltt authentication into your existing user management flow or build a new one from scratch.

Implementing Authentication in Your Application

Now that we understand how to obtain Session tokens, let's explore how to implement authentication in your client-side application.

Client-Side Access

On the client side, your main tasks are:

1. Securely storing the Session token
2. Including the token in API requests

Here's a basic example using JavaScript:

// Import Quiltt's Auth API client
import { AuthAPI } from '@quiltt/core'

// Set up client instance
const auth = new AuthAPI()

// Store the session token from your server
const response = fetch('https://YOUR_SERVER/ENDPOINT', ...)
localStorage.setItem('quilttToken', response.token);

// Retrieve Token
const quilttToken = localStorage.getItem('quilttToken')

// Check if a Session token is valid
auth.ping(quilttToken)

// Querying GraphQL Profile API
fetch('https://api.quiltt.io/v1/graphql', {
  headers: {
    'Authorization': `Bearer ${SESSION_TOKEN}`
  },
  ...
})
    
// Revoke a Session token
auth.revoke(quilttToken)
localStorage.removeItem('quilttToken');

‍

To simplify this process for your preferred platform, we offer a variety of SDKs in our documentation. These include SDKs for HTML, React, React Native, Flutter, iOS, and Android.

Server-Side Access

On the server side, you can use your API Key Secret to access both the Platform REST API and the Profile GraphQL API.

To access the Profile GraphQL API, create a Basic authorization token using the Profile ID and your API Key Secret.

Authorization: Basic <Base64-encoded profileId:API_KEY_SECRET>

token = Base64.strict_encode64("#{profileId}:#{API_KEY_SECRET}")

‍

Best Practices for Quiltt Authentication

To ensure the security and efficiency of your authentication system, consider these best practices:

1. Always use HTTPS to encrypt data in transit.
2. Store tokens securely.
3. Implement token refresh mechanisms to maintain user sessions without requiring frequent logins.
4. Handle authentication errors gracefully, providing clear feedback to users.
5. Implement logout functionality by revoking tokens.
6. Regularly audit your authentication flows to ensure they remain secure as your application evolves.

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.

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.

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 application. Happy coding, and here's to building secure, user-friendly applications!