Sign in with email

All requests go to the Truememory Auth base URL (see Before you start for prerequisites: base URL, CORS whitelisting, OAuth client IDs).

Registration (Email/Password)

Create a new user account. Password must be at least 6 characters.

POST https://your-auth-host/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "display_name": "Jane Doe",
  "app_name": "Vibrantly"
}

app_name is optional — it brands the verification email sent at signup (see Email Verification); omitted, the email uses Truememory branding.

Response (201 Created):

{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "AMf-xB...",
  "expires_in": "3600",
  "user": {
    "id": "4b822c30-1a07-40d6-8d59-321ef99037f6",
    "gip_uid": "5iexdslxx7hFwmKPIdlssLRkREA3",
    "email": "user@example.com",
    "email_verified": false,
    "username": null,
    "display_name": "Jane Doe",
    "photo_url": null,
    "phone_number": null,
    "disabled": false,
    "role": "user",
    "metadata": {},
    "created_at": "2026-03-25T10:00:00Z",
    "updated_at": "2026-03-25T10:00:00Z"
  }
}

All auth endpoints (/register, /login, /oauth/token) return this same response shape: an id_token for authenticating API calls, a refresh_token for getting new tokens when the current one expires, and a user object with the account details.

Error responses:

User IDs

• user.id — Truememory’s canonical user UUID. Deterministic — the same Firebase user always produces the same UUID, across all services, without a central registry or database lookup.
• user.gip_uid — The raw Firebase/GIP UID. Also appears as sub in the JWT.

Login (Email/Password)

POST https://your-auth-host/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Returns the same { id_token, refresh_token, expires_in, user } shape as registration.

Password Reset

The reset flow is two steps: request the email, then confirm the new password using the code from the link.

Step 1 — Request reset email

POST https://your-auth-host/auth/forgot-password
Content-Type: application/json

{ "email": "user@example.com", "app_name": "Vibrantly" }

Always returns { "status": "ok" } regardless of whether the email exists (prevents email enumeration). Firebase sends a password reset email if the account exists.

Step 2 — User completes the reset on the hosted page

The emailed link opens Truememory’s hosted reset page (branded per app_name), where the user chooses a new password — your app doesn’t need to build a reset screen or handle the link at all.

If you run a custom flow instead (e.g. a native in-app reset screen that intercepts the link), extract the oobCode parameter from the link and exchange it yourself — this is the same endpoint the hosted page uses:

POST https://your-auth-host/auth/reset-password
Content-Type: application/json

{
  "oob_code": "<code from the reset link>",
  "new_password": "NewSecurePassword123!"
}

Response (200 OK):

{ "status": "ok" }

Error responses:

Email Verification

When a user registers with email/password, their email_verified field starts as false. Truememory Auth automatically sends a verification email on registration — no extra API call needed.

The user object in all auth responses includes email_verified, so your app can check it and show a verification prompt when it’s false.

Re-send verification email

If the user did not receive the email or the link expired, they can request a new one. Pass app_name (optional) to use your app’s branding on the email and the hosted verification page — same rules as password reset, including the branding registration requirement:

POST https://your-auth-host/auth/send-verification-email
Authorization: Bearer <id_token>
Content-Type: application/json

{ "email": "user@example.com", "app_name": "Vibrantly" }

Response (200 OK):

{ "status": "ok" }

Returns 400 with code AUTH_VERIFICATION_FAILED if the email is already verified.

Checking verification status after the user clicks the link

When the user clicks the verification link, Google Identity Platform marks their email as verified on Google’s side. Your app’s token still carries the old email_verified: false until you refresh it.

The client-side flow:

sequenceDiagram
accTitle: Email Verification Refresh Flow
accDescr: Shows how a client detects email verification after the user clicks the link

    participant User
    participant App as Your App
    participant Truememory as Truememory Auth
    participant GIP as Google Identity Platform

    App->>App: Show "Verify your email" banner
    User->>User: Open email, click verification link
    User->>GIP: Browser opens verification URL
    GIP->>GIP: Mark email as verified
    User->>App: Return to app
    App->>Truememory: POST /auth/refresh { refresh_token }
    Truememory-->>App: New id_token (email_verified: true)
    App->>Truememory: GET /auth/me
    Truememory-->>App: user.email_verified = true
    App->>App: Hide verification banner

When to trigger the refresh — the client should call POST /auth/refresh when it detects the user has returned to the app after clicking the verification link:

// Refresh when the user switches back to the tab
document.addEventListener("visibilitychange", async () => {
  if (document.visibilityState === "visible") {
    const user = getCurrentUser(); // your local user state
    if (user && !user.email_verified) {
      const tokens = await refreshToken(); // POST /auth/refresh
      const me = await fetchMe(tokens.id_token); // GET /auth/me
      if (me.email_verified) {
        // Update local state, hide banner
      }
    }
  }
});

Why OAuth users skip verification

Users who sign in with Google or Apple already have a verified email — the provider confirms it during sign-in. Their email_verified is true from the first login, so no verification email is sent.