Amargi Hub

Overview

Amargi Hub is the shared identity + launcher layer for the Amargi product family. Every product (Reach, Agents, Escalate, Mail, Meet, Remote) uses Hub for:

• Authenticating users (email + password, optional 2FA).
• Issuing JWTs that each product consumes.
• Managing organization membership and roles.
• Providing the launcher that opens each product in one click.

Hub stores ONLY identity data (email, password hash, 2FA, sessions, organization membership). It does NOT store any product data (WhatsApp messages, tickets, agent runs — all of that lives in each product's own database with tenant isolation enforced).

Quickstart

1. Sign up at signin.amargicreative.com. Verify your email.
2. Create a workspace (auto-created on first sign-up; pick the business name).
3. Invite teammates from Settings → Team. Each gets a direct invite link.
4. Open the launcher at app.amargicreative.com to access your connected products.
5. Enable 2FA from Settings → Security. Required for accounts using Meta products (Reach, Escalate).

Key concepts

User, Workspace, Organization

A User is an individual account, identified by email. An Organization is the legal / billing entity — usually your company. A Workspace is an operational container inside an organization — most customers have one workspace per organization; larger teams may use several (per branch, brand, etc.). Resources (WABAs, agents, tickets) belong to a workspace, not directly to an organization.

Roles

• Owner — Full control (billing, suspension, deletion).
• Admin — Product configuration, team management, no billing.
• Member — Day-to-day operational user (sending messages, opening tickets).
• Viewer — Read-only access, useful for external auditors.

Roles are workspace-scoped — the same user can be Admin in one workspace and Viewer in another. Product-specific roles (e.g. "Reach agent can send") exist per product, see the product docs for each.

JWT and JWKS

Hub issues JWTs signed with RS256. The public key is available at the standard JWKS endpoint at https://signin.amargicreative.com/.well-known/jwks.json. Every Amargi product (and any external integration you write) must verify token signatures against the JWKS before accepting the request. JWT claims include:

• sub — User id (UUID).
• org — Active organization id.
• workspace — Active workspace id.
• role — Workspace-scoped role.
• iss — https://signin.amargicreative.com
• aud — amargi-platform (shared across products).

Sessions + cookies

Hub maintains two cookies on the apex domain .amargicreative.com so all subdomain products share the session. The cookies:

• amargi_hub_access — Short-lived JWT (15 minutes) sent on every request.
• amargi_hub_refresh — Long-lived refresh token (30 days) automatically used to renew the access token.

Common tasks

Invite a teammate

1. Settings → Team → Invite
2. Enter email, pick role.
3. Copy the invite link or let Hub email it.
4. The teammate accepts, creates an account, automatically joins the workspace.

Create an API key

1. Settings → API Keys → New Key
2. Give it a descriptive name + pick scopes (read, write).
3. Copy the token immediately — it will NOT be shown again.
4. Use it as Authorization: Bearer <key> in your API requests.

Enable 2FA

1. Settings → Security → Enable 2FA
2. Scan the QR code with an authenticator app (Google Authenticator, 1Password, etc.).
3. Save backup codes somewhere safe.
4. Confirm by entering a current TOTP code.

Revoke a session

1. Settings → Sessions — shows every active session with IP, browser, and last-seen.
2. Click "Revoke" next to any session you don't recognize.
3. Tokens are invalidated immediately; that session is logged out on its next request.

API reference

Public authentication endpoints (no JWT required to reach them):

• POST /api/auth/signup — Create a new account.
• POST /api/auth/login — Sign in; returns cookies.
• POST /api/auth/logout — Clear cookies + invalidate refresh token.
• POST /api/auth/refresh — Refresh access token from refresh token (handled automatically).
• GET /.well-known/jwks.json — Public JWKS key for verifying JWT signatures.

JWT-protected API endpoints (need either the amargi_hub_access cookie or an Authorization Bearer header):

• GET /api/me — Current user profile + organization memberships.
• GET /api/organizations/:id/members — List organization members.
• POST /api/organizations/:id/invites — Invite a member.
• POST /api/api-keys — Create a new API key.

Getting help

• Email support: contact@amargicreative.com
• Billing issue or account deletion: deletion guide.
• Privacy posture + encryption: privacy posture.