Forkr 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 is deployed by default, but routes stay public until you enable protection with 4kr auth settings.
Forkr cannot currently create the standard 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 are not the normal accounts.google.com Web application client that Forkr uses.

​
What Forkr deploys

During deployment, Forkr creates:
  • An auth host at https://auth.<forkr_domain>.
  • /auth/signin, /auth/cli/signin, /auth/callback, /auth/logout, and /auth/verify routes on forkr-api.
  • Traefik forward-auth middleware named forkr-auth.
  • A persistent auth settings file at /var/lib/forks/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.
  • FORKR_AUTH_GOOGLE_CLIENT_ID is the Google OAuth client ID.
  • FORKR_AUTH_GOOGLE_CLIENT_SECRET is the Google OAuth client secret.
The setup CLI generates and stores auth_jwt_secret automatically. 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 forkr-prod-123456, use: 
https://console.cloud.google.com/auth/clients?project=forkr-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 Forkr deployment, for example Forkr 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.<forkr_domain>/auth/callback
For example, if your Forkr domain is 4kr.example.com, the redirect URI is: 
https://auth.4kr.example.com/auth/callback
Save the credentials into the setup profile: 
4kr config set profile prod
4kr config set google_workspace_domain example.com
4kr config set google_auth_client_id <client-id>
4kr config set google_auth_client_secret <client-secret>
google_workspace_domain seeds the default allowed Google Workspace domain. You can still add or replace allowed domains and emails later. If you are using 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 then store the downloaded credentials in the Forkr setup profile.

​
Deploy auth configuration

Run deploy after adding or changing the Google OAuth credentials: 
4kr setup deploy
Deployment injects the profile values into forkr-api as: 
AUTH_JWT_SECRET
FORKR_AUTH_GOOGLE_CLIENT_ID
FORKR_AUTH_GOOGLE_CLIENT_SECRET
FORKR_AUTH_REDIRECT_URI
FORKR_AUTH_COOKIE_DOMAIN
FORKR_AUTH_WORKSPACE_DOMAIN
The default redirect URI, cookie domain, and auth host are derived from the Forkr domain: 
FORKR_AUTH_REDIRECT_URI=https://auth.<forkr_domain>/auth/callback
FORKR_AUTH_COOKIE_DOMAIN=.<forkr_domain>
FORKR_AUTH_WORKSPACE_DOMAIN=<google_workspace_domain>

​
Sign in from the CLI

After deploy, sign in with Google: 
4kr auth signin
This opens a browser, completes Google sign-in, mints a Forkr JWT, and stores it as auth_token in the local profile config. Print the stored token for agents and scripts: 
4kr auth token
The API accepts either the static deployment token or a valid Google-auth JWT: 
curl -H "Authorization: Bearer $(4kr auth token)" \
  https://api.<forkr_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: 
4kr auth settings --protect-unpublished --protect-system
--protect-unpublished applies to box hosts under the Forkr domain. --protect-system applies to system domains such as API and dashboard routes. Published app URLs remain public by default. Require auth for a specific box: 
4kr auth box my-box --required
Make a box public even when the global unpublished-box default requires auth: 
4kr auth box my-box --public
Return a box to the global default: 
4kr auth box my-box --inherit

​
Control who can sign in

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

​
Troubleshooting

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