Authentication

End users log in to Gommo and receive an access_token. Your app or browser keeps the token and sends it on each request.

API credentials and security

Rule	Why
Store `access_token` on your server (env, secret manager, per-user session store)	Tokens are equivalent to account access and credits
Do not ship long-lived tokens in mobile apps, browser bundles, or public repos	Anyone with the token can spend credits and call APIs as the user
Send `domain` on login, create, poll, and `ai/me`	Registration domain must match signup — Registration domain
Rotate or revoke if leaked	Use Gommo account / dealer tools; re-login to issue a new token
Merchant `GOMMO_ACCESS_TOKEN` (register, sendBalances)	Server-only — never expose to clients

Docs examples use $env:TOKEN or %TOKEN% for clarity. Production integrations should use your auth layer, not copy-paste tokens into frontends. After login, follow Request lifecycle for media jobs.

Public Gommo API (recommended)

Operation	URL
Login	`POST https://api.gommo.net/api/apps/go-mmo/auth/login`
Register (merchant, server)	`POST https://api.gommo.net/api/apps/go-mmo/auth/register`
Change password	`POST https://api.gommo.net/api/apps/go-mmo/auth/change-password`
Transfer credits (P2P)	`POST https://api.gommo.net/api/apps/go-mmo/users/sendBalances`
Transaction history (ledger)	`POST https://api.gommo.net/api/apps/go-mmo/users/paymentsHistory`
Session devices	`POST https://api.gommo.net/api/v2/devices`
Me / credits	`POST https://api.gommo.net/ai/me`

Form body: email, password, domain (login); merchant fields + email, password, phone, domain (register — server only); access_token, domain, current_password, new_password (change password); access_token, domain, type, value, username, message (transfer); access_token, domain, limit, time_start, time_end, optional currency_name, source, language (ledger); access_token, domain, action, optional current_device_id, device_id, device_name, device_info, language (session devices); or access_token, domain (me). Header: Authorization: Bearer <token> when using Bearer style.

→ Gommo public API · Sign up · Change password · Transfer credits · Transaction history · Session devices · Support tickets · Partner program · Creator rewards · Quickstart

Playground — auth API tests vs Connection

Playground — System → Login API (test) and Register API (test) call POST /gateway/auth/login and /gateway/auth/register and show JSON like other workers. They do not save a token or change Connection (use Connection → Sign in, or /signup/, to persist a session). Registration domain is resolved from the active dealer tenant on the server — not a form field in Playground. Register requires merchant env on the gateway (GOMMO_ACCESS_TOKEN, GOMMO_MANAGER_ID). Direct Gommo API (Mode A) still requires domain in the form body where applicable.

Home feed → Platform — Change password, Transfer credits, Transaction history, Session devices, Support tickets, Partner program, and Creator Rewards use your connected Bearer (see change password, transfer credits, transaction history, session devices, support tickets, partner program, creator rewards).

Wrong domain

The domain form field is the user's registration domain on Gommo (dealer tenant) — not api.gommo.net or v2.api.gommo.net. It must match where the user signed up. Do not copy a domain from these docs. Wrong domain → auth failure, wrong credits, or billing on the wrong dealer.

Registration domain

Source	Use when
User signup / dealer docs	Production — each user has a fixed registration domain
`$env:GOMMO_API_DOMAIN` (PowerShell)	Scripts — set before running examples
`%REGISTRATION_DOMAIN%` (curl.exe)	Windows curl — set in your shell session
`config/docs-sites.json`	Self-hosted portal — `docsHost` → `registrationDomain`; localhost uses `defaultDocsHost`

Integrators store the registration domain per user (from your signup flow). Never hardcode a dealer domain in app code.

The docs site (:5173 in dev) includes a built-in account flow:

Page	URL
Sign in	`/login/`
Sign up	`/signup/`
Dashboard (after login)	`/app/`

After a successful sign-in or sign-up, the browser redirects to /app/ (Overview). The access token is stored in localStorage as gw_access_token. Profile and credits load from POST https://api.gommo.net/ai/me.

Dev token paste

On /login/, switch to the Bearer token tab to paste an existing Gommo access_token (useful for testing without email/password).

Cursor MCP (Gommo)

After sign-in, copy your token from /app/token/ into Gommo MCP. See all 10 tools and example prompts.

curlPowerShell

bash

curl.exe -X POST "https://api.gommo.net/api/apps/go-mmo/auth/login" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "[email protected]&password=YOUR_PASSWORD&domain=%REGISTRATION_DOMAIN%"

powershell

$domain = $env:GOMMO_API_DOMAIN; if (-not $domain) { throw 'Set GOMMO_API_DOMAIN to the user registration domain (dealer)' }
$body = "[email protected]&password=YOUR_PASSWORD&domain=$domain"
$login = Invoke-RestMethod -Method POST `
  -Uri "https://api.gommo.net/api/apps/go-mmo/auth/login" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body $body
$env:TOKEN = $login.access_token

Response contains access_token — store as $TOKEN.

User token usage

Use the access_token on all Gommo API calls.

Domain: include domain in every form body (registration domain — must match user signup). Match the domain the user registered with.

Bearer header (V2 jobs, optional on platform)

Authorization: Bearer {access_token}

Form field (platform / chat / audio)

access_token={token}&domain={domain}

V2 media jobs (Mode A)

Header: Authorization: Bearer {access_token}
Form body: domain, project_id, prompt, ratio, …

powershell

$h = @{
  Authorization = "Bearer $env:TOKEN"
  'Content-Type' = 'application/x-www-form-urlencoded'
}

Platform / chat / audio (form)

Form field: access_token={token}
Form field: domain — registration domain (dealer-specific — do not copy from docs)

Check session (`/ai/me`)

Load the signed-in user and credit balance. The docs dashboard (/app/) and billing top-up use this endpoint.

curl — Direct (recommended)PowerShellcurl — Bearer header

bash

curl.exe -X POST "https://api.gommo.net/ai/me" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "access_token=%TOKEN%&domain=%REGISTRATION_DOMAIN%"

powershell

$domain = $env:GOMMO_API_DOMAIN; if (-not $domain) { throw 'Set GOMMO_API_DOMAIN to the user registration domain (dealer)' }
$meBody = "access_token=$env:TOKEN&domain=$domain"
Invoke-RestMethod -Method POST `
  -Uri "https://api.gommo.net/ai/me" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body $meBody

bash

curl.exe -X POST "https://api.gommo.net/ai/me" ^
  -H "Authorization: Bearer %TOKEN%" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "domain=%REGISTRATION_DOMAIN%"

Response includes access_token — use as Authorization: Bearer … for subsequent calls.

Include device_id, device_name, and device_info in the form body (same as Gommo platform apps) so balancesInfo.credits_ai is populated.

Admin / merchant (server-only)

/admin/* routes do not use the user Bearer token.

Header	Server env
`x-admin-key: {ADMIN_API_KEY}`	`ADMIN_API_KEY`

→ Admin reference

Optional: self-host (operators)

Deploying this repo (npm run dev, Docker) adds optional JSON and proxy mounts for portal, billing, and BYOK previews — not part of the public Gommo integration contract.

→ Deploy & ops → Self-host (advanced)

Authentication ​

API credentials and security ​

Public Gommo API (recommended) ​

Registration domain ​

Sign in on the developer site ​

Login direct (Mode A) ​

User token usage ​

Bearer header (V2 jobs, optional on platform) ​

Form field (platform / chat / audio) ​

V2 media jobs (Mode A) ​

Platform / chat / audio (form) ​

Check session (/ai/me) ​

Admin / merchant (server-only) ​

Optional: self-host (operators) ​

Authentication

API credentials and security

Public Gommo API (recommended)

Registration domain

Sign in on the developer site

Login direct (Mode A)

User token usage

Bearer header (V2 jobs, optional on platform)

Form field (platform / chat / audio)

V2 media jobs (Mode A)

Platform / chat / audio (form)

Check session (`/ai/me`)

Admin / merchant (server-only)

Optional: self-host (operators)