DOCSEARCHbyAlgolia
Submit Docs

Hexclave Documentation

repository·dev·Indexed 27 days ago

https://github.com/hexclave/hexclave

A user infrastructure platform for authentication, teams, payments, emails, and analytics. Documentation covers contact channel management, primary email verification, asynchronous email infrastructure via the EmailOutbox pipeline, API versioning and migration strategies, and local documentation development using Mintlify.

Tokens
144.5K
Snippets
346
Records
840
Agent score
91%

What's inside Hexclave

  1. Overview of Hexclave features

    dev

    Hexclave is a user infrastructure platform that provides a catalog of modular apps built on a unified user model. Key features include:

    • Authentication: Supports passkeys, OAuth, and CLI auth. Methods can be toggled via the dashboard without code changes.
    • Teams: Provides workspaces, email invites, and role-based management.
    • RBAC (Role-Based Access Control): Nested roles and unified permission checks for both server and client.
    • API Keys: Secure key management with auto-revocation for leaked keys.
    • Payments: Handles subscriptions, one-time charges, and usage metering with credits for individuals or teams.
    • Emails: Unified API for transactional and marketing emails with AI-assisted template editing.
    • Analytics: Live active user counts and session replays; supports natural language dashboard building or SQL queries.
    • Webhooks: Signed, tamper-proof real-time event notifications with built-in retries and backoff.
    • Data Vault: Secure, server-only storage for user secrets, encrypted with your own secret.
    • Launch Checklist: A production readiness tracker for domain setup, callbacks, and secret rotation.

  2. Overview of Hexclave User Infrastructure

    dev

    Hexclave is a unified developer platform for user management and user infrastructure. It provides a single integrated solution for features that typically require multiple vendors, including:

    • Authentication: Identity, sign-in, and account management.
    • Teams & Orgs: Modeling users, organizations, and teams.
    • RBAC: Role-Based Access Control.
    • Payments: Billing, subscriptions, and payment processing.
    • Emails: Transactional and lifecycle emails.
    • Analytics: Product analytics and user instrumentation.
    • Webhooks & API Keys: Managing integrations and secure access.

    Hexclave is designed to replace the manual process of stitching together separate services like Stripe (payments), Resend (emails), and Segment (analytics).

  4. Use ServerTeam for Administrative Access

    dev

    The ServerTeam object extends the standard Team object. It is intended for use with HexclaveServerApp and provides full read/write access without the permission checks required by the standard Team object.

    If the current user is a ServerUser, calling serverUser.getTeam(...) or serverUser.listTeams() will return ServerTeam objects. You can also query teams directly via:

    • hexclaveServerApp.getTeam(teamId)
    • hexclaveServerApp.listTeams()

  5. Use the Customer interface for payments and item management

    dev

    The Customer interface provides payment and item management functionality. It is shared between users and teams, meaning both CurrentUser and Team types extend this interface. This allows you to create checkout URLs and manage items regardless of whether the context is an individual user or an organization.

    The Customer interface is automatically available on:

    • CurrentUser objects
    • Team objects
    • ServerUser objects (includes additional server-side capabilities)
    • ServerTeam objects (includes additional server-side capabilities)

  6. Hexclave Documentation Roadmap

    dev

    The Hexclave documentation is organized into several key areas to help you integrate authentication, teams, RBAC, and more:

    • Getting Started: Covers first-time setup, SDK installation, user fundamentals, AI integration, and production launch checklists.
    • Explore Apps: Guides for implementing specific features like Authentication.
    • Going Further: Advanced configuration including Local vs. Cloud development, the Hexclave Config File, and CLI usage.
    • SDK Reference: Detailed documentation for using hooks, objects, and types (e.g., useUser, StackApp, User type) to manage auth data in your application code.
    • REST API: Instructions for integrating Hexclave via HTTP endpoints and webhooks from any backend or language.

  7. Understand Primary Email and Contact Channel concepts

    dev

    In Hexclave, users can have multiple contact channels (currently only email type is supported). One of these is designated as the primary email, which is the main email address for the user account.

    Key Concepts

    • Contact Channel: A communication endpoint (email) associated with a user.
    • Primary Email: The main email address for a user, reflected in user.primary_email.
    • Verified: Indicates if email ownership has been confirmed.
    • Used for Auth: Indicates if the email can be used to sign in.

    Data Model Relationship

    The following fields on the User object are derived from the contact channel where is_primary = true:

    • primary_email
    • primary_email_verified
    • primary_email_auth_enabled

  8. Understand Hexclave customer types

    dev

    Hexclave categorizes payment customers into three types, which determines how they are managed and which SDK methods are available:

    • Users: Individual accounts. They can manage their own purchases, billing, and invoices using the client SDK.
    • Teams: Organization accounts. Team admins can manage checkouts, switch plans, and cancel subscriptions.
    • Custom customers: External entities identified by a string ID. These are managed exclusively via the server SDK and do not support billing or invoices.

    Note: Client-side methods like createCheckoutUrl, useProducts, useItem, switchSubscription, useBilling, and useInvoices work for Users and Teams. For Custom customers, you must use top-level hexclaveServerApp methods with the customCustomerId parameter.

  10. Integrate Hexclave with Convex

    dev

    To integrate Hexclave with a Convex + Next.js application, follow these steps:

    1. Initialize Convex + Next.js: Run npm create convex@latest and select "Next.js" and "No auth". Start the backend with npx convex dev and the dev server with npm run dev.
    2. Install Hexclave: Use the Hexclave setup prompt (available via the Hexclave dashboard/setup builder) and select Next.js and Convex.
    3. Configure Environment Variables:
      • Create a Hexclave project at app.hexclave.com.
      • Add HEXCLAVE_PROJECT_ID and your API key to your .env.local file.
      • Add the same environment variables to your Convex deployment dashboard.
    4. Configure Authentication: Update convex/auth.config.ts to use getConvexProvidersConfig and update your Convex client to use Hexclave's auth methods.
    npm create convex@latest
# Choose "Next.js" and "No auth"

npx convex dev
npm run dev

  11. Configure a Local Development Environment

    dev

    Use a local development environment when you want to keep your Hexclave configuration (auth settings, RBAC, email templates, etc.) in source control and allow teammates to review changes via pull requests. This setup uses a hexclave.config.ts file and the Hexclave CLI.

    1. Create a hexclave.config.ts file in your project root:
    import type { HexclaveConfig } from "@hexclave/js";

export const config: HexclaveConfig = "show-onboarding";
    1. Update your package.json to include a dev script that invokes the Hexclave CLI:
    {
  "scripts": {
    "dev": "hexclave dev --config-file ./hexclave.config.ts -- npm run dev:inner",
    "dev:inner": "<your-existing-dev-script>"
  }
}
    import type { HexclaveConfig } from "@hexclave/js";

export const config: HexclaveConfig = "show-onboarding";

  12. Create User API keys

    dev

    User API keys are associated with individual users and allow them to authenticate with your API programmatically. You can create these keys using the Hexclave SDKs (Next.js, React) or via direct HTTP requests to the Hexclave API.

    Using SDKs

    Next.js Client

    const user = useUser({ or: 'redirect' });
const apiKey = await user.createApiKey({
  description: "My client application",
  expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
});

    Next.js Server

    const user = await hexclaveServerApp.getUser({ or: 'redirect' });
const apiKey = await user.createApiKey({
  description: "Admin-provisioned API key",
  expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
});

    React

    const user = useUser({ or: 'redirect' });
const apiKey = await user.createApiKey({
  description: "My client application",
  expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)),
});

    Using HTTP API

    To create a user API key via HTTP, send a POST request to https://api.hexclave.com/api/v1/user-api-keys. You must include the following headers and JSON body:

    Headers:

    • x-stack-access-type: client
    • x-stack-project-id: Your project ID
    • x-stack-publishable-client-key: Your publishable client key
    • x-stack-access-token: The user's current access token (e.g., from a session cookie)

    JSON Body:

    • user_id: Set to 'me' for the current user
    • description: A string describing the key
    • expires_at_millis: Expiration timestamp in milliseconds
    "use client";
import { useUser } from "@hexclave/next";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}