Zomg uses Google OAuth for browser sign-in and short-lived user tokens. The same auth service protects dashboard routes, API calls, CLI tokens, unpublished box URLs, and published box URLs when you opt in. Auth is configured per deployment profile. The auth service deploys by default, but routes stay public until you enable protection with zomg auth settings.
Zomg can’t create the Google Auth Platform Web application OAuth client for you through a supported Google API. Google exposes programmatic OAuth-client APIs for IAP and workforce flows, but those clients aren’t the normal accounts.google.com Web application client that Zomg uses.

​
What Zomg deploys

During deployment, Zomg creates:
  • An auth host at https://auth.<zomg_domain>.
  • /auth/signin, /auth/cli/signin, /auth/callback, /auth/logout, and /auth/verify routes on zomg-api.
  • Traefik forward-auth middleware named zomg-auth.
  • A persistent auth settings file at /var/lib/boxes/data/auth/settings.json.
The auth service needs three secrets or values to be fully configured:
  • AUTH_JWT_SECRET signs browser session tokens and CLI auth tokens.
  • ZOMG_AUTH_GOOGLE_CLIENT_ID is the Google OAuth client ID.
  • ZOMG_AUTH_GOOGLE_CLIENT_SECRET is the Google OAuth client secret.
The setup CLI generates and stores auth_jwt_secret for you. You provide the Google OAuth client ID and secret.

​
Create the Google OAuth client

Create a Google OAuth Web application client in the same Google Cloud project you use for the deployment. Open the Auth Platform clients page for your deployment project: 
https://console.cloud.google.com/auth/clients?project=<gcp_project>
For example, if your deployment project is zomg-prod-123456, use: 
https://console.cloud.google.com/auth/clients?project=zomg-prod-123456
In the Google UI:
  1. Click Create client or Create OAuth client.
  2. Choose Web application as the application type.
  3. Name it for the Zomg deployment, for example Zomg prod.
  4. Add the authorized redirect URI shown below.
  5. Create the client.
  6. Copy or download the client ID and client secret.
Use this exact authorized redirect URI: 
https://auth.<zomg_domain>/auth/callback
For example, if your Zomg domain is zomg.example.com, the redirect URI is: 
https://auth.zomg.example.com/auth/callback
Save the credentials into the setup profile: 
zomg config set profile prod
zomg config set google_workspace_domain example.com
zomg config set google_auth_client_id <client-id>
zomg config set google_auth_client_secret <client-secret>
google_workspace_domain seeds the default allowed Google Workspace domain. You can add or replace allowed domains and emails later. If you use Codex or another browser-capable agent, you can ask it to open the Auth Platform clients page, create the Web application client, confirm the redirect URI, and store the downloaded credentials in the Zomg setup profile.

​
Deploy auth configuration

Run deploy after adding or changing the Google OAuth credentials: 
zomg setup deploy
Deployment injects the profile values into zomg-api as: 
AUTH_JWT_SECRET
ZOMG_AUTH_GOOGLE_CLIENT_ID
ZOMG_AUTH_GOOGLE_CLIENT_SECRET
ZOMG_AUTH_REDIRECT_URI
ZOMG_AUTH_COOKIE_DOMAIN
ZOMG_AUTH_WORKSPACE_DOMAIN
The default redirect URI, cookie domain, and auth host are derived from the Zomg domain: 
ZOMG_AUTH_REDIRECT_URI=https://auth.<zomg_domain>/auth/callback
ZOMG_AUTH_COOKIE_DOMAIN=.<zomg_domain>
ZOMG_AUTH_WORKSPACE_DOMAIN=<google_workspace_domain>

​
Sign in from the CLI

After deploy, sign in with Google: 
zomg auth signin
This opens a browser, completes Google sign-in, mints a Zomg JWT, and stores it as auth_token in the local profile config. Print the stored token for agents and scripts: 
zomg auth token
The API accepts either the static deployment token or a valid Google-auth JWT: 
curl -H "Authorization: Bearer $(zomg auth token)" \
  https://api.<zomg_domain>/v1/projects/default/boxes

​
Enable route protection

Routes are public until you enable protection. This lets you deploy and test before enforcing browser sign-in. Protect unpublished box URLs and system domains: 
zomg auth settings --protect-unpublished --protect-system
--protect-unpublished applies to box hosts under the Zomg domain. --protect-system applies to system domains like API and dashboard routes. Published app URLs stay public by default. Require auth for a specific box: 
zomg auth box my-box --required
Make a box public even when the global unpublished-box default requires auth: 
zomg auth box my-box --public
Return a box to the global default: 
zomg auth box my-box --inherit

​
Control who can sign in

By default, Zomg allows users from google_workspace_domain when it is set. You can replace the allowed domain list or add explicit emails: 
zomg auth settings --allowed-domain example.com
zomg auth settings --allowed-email alice@example.com
Allow any Google account: 
zomg auth settings --allow-all-google-accounts
Return to domain/email restrictions: 
zomg auth settings --workspace-only
Inspect the effective settings: 
zomg auth settings

​
Troubleshooting

If zomg auth settings prints configured=false, redeploy after setting all required values: 
zomg config set google_auth_client_id <client-id>
zomg config set google_auth_client_secret <client-secret>
zomg setup deploy
If Google returns a redirect mismatch, check the OAuth client’s authorized redirect URI. It must exactly match: 
https://auth.<zomg_domain>/auth/callback
If browser sign-in succeeds but CLI or API calls fail, run zomg auth signin again and confirm the selected profile points at the deployed API: 
zomg config get profile
zomg auth token --json