Auth Apps

Provision hosted authentication services for your deployed applications. Each auth app gets JWT signing keys, an OAuth layer (email/password + optional Google and GitHub), and URLs under auth.ghayma.tech that your application code calls for register / login / refresh / JWKS.

One Ghayma project can host multiple auth apps.

ghayma auth create

Create a new managed auth app tied to a project.

ghayma auth create my-auth --app-id my-app-auth
 
# Pick a user-capacity bracket and turn on 2FA
ghayma auth create my-auth --app-id my-app-auth --users 10k --2fa
 
# Connect it to the 'main' site as it is created
ghayma auth create my-auth --app-id my-app-auth --site main

Flags:

A new auth app is connected only to the sites you choose, at level client. With neither flag the CLI asks on a terminal, while a script connects nothing and prints the ghayma connect auth … command — exactly as ghayma db create does. A site receives the app’s variables once it is connected.

Sizing and points

An auth app reserves points for its user-capacity bracket, plus a flat add-on for 2FA (see Pricing by Service). Pass --users and --2fa to set these non-interactively. If you pass neither, auth create opens interactive pickers, each choice showing its points cost:

Select a user-capacity bracket
  ▸ 1k — up to 1000 users · 1 pts
    10k — up to 10000 users · 3 pts
    100k — up to 100000 users · 6 pts
Enable two-factor auth (2FA)?
  ▸ No
    Yes — +1 pts

Before the app is created, the CLI previews the points it will reserve for the full total (bracket + 2FA):

This auth app will reserve 4 pts · 46 remaining after

Output:

✅ Created auth app 'my-auth'
   App ID:    my-app-auth
   Status:    active
   Enabled:   2FA
🔗 Connected to 'main'

📋 Endpoints:
   Register:  POST https://auth.ghayma.tech/v1/my-app-auth/register
   Login:     POST https://auth.ghayma.tech/v1/my-app-auth/login
   JWKS:      GET  https://auth.ghayma.tech/v1/my-app-auth/.well-known/jwks.json

📋 Next steps:
   ghayma auth config my-auth --google-client-id <id> --google-client-secret <secret>

The Enabled: line appears only when you pass --2fa. 2FA isn’t set at creation directly: the app is created at its bracket first, then 2FA is turned on with a follow-up configuration step. If that step is rejected for points, the app still exists at its bracket and the CLI tells you how to recover:

⚠️  Auth app created at bracket '10k', but enabling 2FA failed:
<reason>
   Free up points, then enable them from the dashboard (or delete and recreate).

ghayma auth list

List every auth app you own across all projects.

ghayma auth list

Output:

🔐 Your auth apps (2):

   my-auth               my-app-auth     active    providers: email, google
   admin-portal-auth     admin-auth      active    providers: email

Columns are name, app-id, status, and the list of enabled providers. Email/password is always enabled; Google and GitHub appear only when they have a client ID configured.

ghayma auth info

Show configuration + full endpoint list for a single auth app.

ghayma auth info my-auth

Output:

🔐 Auth App: my-auth

   App ID:         my-app-auth
   Status:         active
   JWT Expiry:     3600s
   Refresh Expiry: 604800s
   Email Verify:   true

   Providers:
   ✅ Email/Password (always enabled)
   ✅ Google (client: 123456789012-abcdef...)
   ❌ GitHub (not configured)

   Allowed Origins: https://preview.example.com, com.example.app://callback

📋 Endpoints:
   Register:        POST https://auth.ghayma.tech/v1/my-app-auth/register
   Login:           POST https://auth.ghayma.tech/v1/my-app-auth/login
   Refresh:         POST https://auth.ghayma.tech/v1/my-app-auth/refresh
   Logout:          POST https://auth.ghayma.tech/v1/my-app-auth/logout
   Forgot Password: POST https://auth.ghayma.tech/v1/my-app-auth/forgot-password
   JWKS:            GET  https://auth.ghayma.tech/v1/my-app-auth/.well-known/jwks.json
   Google OAuth:    GET  https://auth.ghayma.tech/v1/my-app-auth/auth/google?redirect_uri=<url>

OAuth endpoint rows only appear for providers that are configured. Allowed Origins lists only the app’s own entries, and only when it has some; the project’s domains and localhost are allowed on top of them.

ghayma auth config

Update settings on an existing auth app. You can pass any combination of these flags in one call — the CLI only sends the ones you provide.

ghayma auth config my-auth \
  --google-client-id 123456789012-abcdef.apps.googleusercontent.com \
  --google-client-secret GOCSPX-...
 
ghayma auth config my-auth --email-verify true
ghayma auth config my-auth --allowed-origins "https://preview.example.com,com.example.app://callback"
ghayma auth config my-auth --jwt-expiry 1800 --refresh-expiry 604800

Flags:

Output (confirmation echoes the updated keys; secret-like keys are redacted so they aren’t written to your terminal scroll-back):

✅ Auth app 'my-auth' updated
   google_client_id = 123456789012-abcdef.apps.googleusercontent.com
   google_client_secret = <redacted>

Running auth config with no flags prints the list of available flags instead of making a request.

Every domain of every site in the app’s project, and http://localhost / http://127.0.0.1 on any port, are always allowed: --allowed-origins is only for other origins, such as a frontend hosted elsewhere, a preview URL or a mobile deep link. Each entry is scheme://host[:port] with no path; * is refused. See Allowed origins.

ghayma auth users

List users registered through an auth app.

ghayma auth users my-auth

Output:

👥 Users for 'my-auth' (3 total):

   [email protected]            email     verified:✅
   [email protected]              google    verified:✅
   [email protected]           email     verified:❌ [DISABLED]

Columns are email, provider (email, google, or github), and verification status. Disabled users have a [DISABLED] marker.

When there are no users, prints No users registered for '<name>'.

ghayma auth stats

Show aggregate usage stats for an auth app. The exact fields returned depend on the server version.

ghayma auth stats my-auth

Output (keys printed are whatever the server returns):

📊 Stats for 'my-auth':

   total_users:         42
   verified_users:      38
   ...

ghayma auth rotate-keys

Rotate the JWT signing keys for an auth app. Asks for confirmation first because existing tokens issued under the old keys will all stop verifying:

⚠️  Rotating keys will invalidate all existing JWT tokens for 'my-auth'. Continue? (y/n):

Output:

✅ JWT signing keys rotated for 'my-auth'. All existing tokens are now invalid.

Users will need to sign in again; your application servers will pick up the new keys automatically from the JWKS endpoint (no redeploy needed).

ghayma auth delete

Permanently delete an auth app and all its registered users. Requires typing the auth app name to confirm:

⚠️  This will permanently delete auth app 'my-auth' and ALL its users.
   Type the name to confirm:

ghayma auth delete my-auth