App users - sign-in owned by your app

An app in app mode (gipity project auth app, or both to also offer Sign in with Gipity) has its own users: people sign in to this app only, with no Gipity account and no consent screen, and the app owns them. Use it for anything you put in front of the public; use Sign in with Gipity for your own tools and for AI apps where users pay for their AI use (see app-auth).

Using it

Turn it on in gipity.yaml (a top-level block, applied by every deploy):

auth:
  mode: app        # or both, to offer Sign in with Gipity too

(gipity project auth app sets it at once and writes that block.) Then the same client code works, with no new endpoints to call; Gipity.auth.signInAsGuest() signs a browser in as its guest with no prompt (for "no sign-in" apps):

const user = await Gipity.auth.signIn();   // opens the app's own sign-in page in a popup
// user: { guid, displayName, avatarUrl, email, provider }   (provider: 'google' | 'discord' | 'apple' | 'email')
await Gipity.auth.user();                  // the signed-in user, or null
await Gipity.auth.signOut();               // this browser
await Gipity.auth.signOutEverywhere();     // every device

The sign-in page is branded as your app (name, logo and accent color from gipity brand / the auth_branding: deploy phase) and offers each provider that is set up plus an email code. A signed-in browser holds an httpOnly session cookie for your app only (30 days, renewed on use, revocable): page JavaScript never sees a token, and another app's code can't use it.

In functions an app user is an ordinary signed-in user (ctx.auth.userGuid, displayName), plus ctx.auth.identity = { provider, id, email }. email is their verified address (null for Steam and guest players), so the app can email its own users with the email() service. Gipity-account callers have identity: null and no email.

One person is one user per app. A provider seen before signs in to its user; a new provider whose verified email matches an existing user links to that user (sign in with Google today, an email code tomorrow: same userGuid). An unverified email never links. The same person in two different apps is two separate users.

Providers and credentials. gipity project auth shows each provider's state.

• Google, Discord: work right away on Gipity's shared credentials; the provider's screen says "Gipity Apps". Fine while you build. Before the app goes public on a custom domain, set your own so the screen shows your app: gipity project auth provider google prints the redirect URI and steps, then gipity project auth provider google --client-id <id> --client-secret <secret>. Existing users carry over (Google ids are the same across credentials). gipity project auth warns when an app with a custom domain still uses shared credentials.
• Apple: needs your own credentials from day one (gipity project auth provider apple), because Apple ties user ids to the developer team.
• Email codes: always on in app mode; sent branded as your app, rate-limited per address.

Lifecycle hooks. Declare functions with hooks: in gipity.yaml (use auth: member so only the platform and you can run them):

• user_created: runs after a new user signs up, with ctx.trigger = { type: 'user_created', userGuid, user: { provider, displayName, email } }. Use it for a welcome email or a profile row. Sign-up never waits on it; failures show in gipity logs fn <name>.
• user_deleted: runs before a user is erased (they deleted their account with DELETE /api/<PROJECT_GUID>/auth/player, or you did); delete their rows. A failure stops the deletion with 502 PLAYER_CLEANUP_FAILED.

Managing users (owner): gipity project users lists and searches them, gipity project users export --format csv -o users.csv exports all, gipity project users delete <guid> erases one (running user_deleted hooks), and gipity project users signout <guid> ends all of their sessions.

Native clients (games, mobile, desktop) don't use the page or the cookie: they sign in over HTTPS and send the returned token as Authorization: Bearer. Steam and guest devices: see steam-game. Email codes: POST /api/<PROJECT_GUID>/auth/email/start { email }, then POST /api/<PROJECT_GUID>/auth/email/verify { email, code }, which returns { data: { token, expiresIn, user } }.

Limits. App users have no Gipity credits, so user_pays services can't bill them; those calls are billed to you (owner pays). There are no passwords, MFA or organizations; if an app needs those, it needs a dedicated identity provider.