Skip to main content

Getting Started

Get up and running with the Users API in your React/Vite project in minutes.

Prerequisites​

Before you begin, ensure you have:

  • A React/Vite project (or create one with npm create vite@latest)
  • Access to a Users API instance (or deploy your own)
  • Admin access to the Users API web dashboard

Step 1: Create Your App Instance​

Before integrating the API into your frontend, you need to create an app instance in the Users API web dashboard.

Access the Admin Dashboard​

  1. Navigate to your Users API instance URL (e.g., https://users-api.brainylab.io)
  2. You'll see the login page for the admin dashboard

Log In​

  1. Enter your admin credentials:
    • App ID: Your admin sourceAppId (typically "admin" or provided by your API administrator)
    • Password: Your admin password
  2. Click "Sign in"

Create a New App​

  1. Once logged in, you'll see the admin dashboard with an Apps section
  2. Click the "Create App" button (or similar action button)
  3. Enter your app identifier (sourceAppId):
    • Must be 1-80 characters
    • Can contain letters, numbers, dots, underscores, and hyphens (a-zA-Z0-9._-)
    • Example: my-marketing-site or landing-page-2024
  4. Click confirm

Save Your Credentials​

After creating the app, the dashboard will display:

  • App ID (sourceAppId): The identifier you just created
  • Password: A randomly generated password

Important: Save the password immediately - it's only shown once and cannot be retrieved later. You'll need this password if you want to access the dashboard for this specific app later.

Configure Schema (Optional)​

After creating the app, you can optionally configure the user schema:

  • Click the "Settings" button next to your app in the Apps table
  • Define which fields users can submit (e.g., fullName, age, consentRequired)
  • Set which fields are required
  • Configure validation rules

If you don't configure a custom schema, the app will use the default schema with common fields like fullName, age, and consent checkboxes.

Step 2: Integrate into Your Frontend​

Now that you have your app credentials, proceed to integrate the API into your React/Vite project.

1. Create a Config File​

Create src/config/users.ts with hardcoded production values:

/**
 * Users service configuration.
 *
 * Production values are hardcoded. For local development, you can override
 * USERS_API_BASE_URL by setting VITE_USERS_API_BASE_URL in .env file.
 */

// Production API URL (can be overridden with VITE_USERS_API_BASE_URL for local dev)
export const USERS_API_BASE_URL =
  import.meta.env.VITE_USERS_API_BASE_URL || "https://users-api.brainylab.io";

// App identifier - unique per project
export const USERS_APP_ID = "my-app-id";

Key Points:

  • Production API URL is hardcoded (no env vars needed in production)
  • App ID is hardcoded per project (replace "my-app-id" with your actual app ID)
  • Optional .env file can override API URL for local development only

2. Submit User Data​

Create a function to submit user data:

async function submitUser(email: string, data: Record<string, unknown>) {
  const url = `${USERS_API_BASE_URL}/v1/users`;

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-app-id": USERS_APP_ID,
    },
    body: JSON.stringify({ email, data }),
  });

  if (!res.ok) {
    const data = (await res.json().catch(() => ({}))) as {
      message?: unknown;
    };
    const message =
      typeof data?.message === "string" ? data.message : "Request failed";
    throw new Error(message);
  }

  return await res.json();
}

3. Use in Your Component​

import { useState } from "react";
import { submitUser } from "./api";

function MyForm() {
  const [email, setEmail] = useState("");
  const [fullName, setFullName] = useState("");
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsSubmitting(true);

    try {
      await submitUser(email, {
        fullName,
        consentRequired: true,
      });
      alert("Success!");
    } catch (error) {
      alert(
        `Error: ${error instanceof Error ? error.message : "Unknown error"}`
      );
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <input
        type="text"
        value={fullName}
        onChange={(e) => setFullName(e.target.value)}
        placeholder="Full Name"
      />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Submitting..." : "Submit"}
      </button>
    </form>
  );
}

What's Next?​