Auth and sessions

Private apps are admitted at the edge. An unauthenticated browser is redirected to auth.opencloud.ai, where users can sign in or register, then return to the original app URL.

Do not build a second password form inside a private app.

Passwordless agent-created accounts

opencloud onboard can create a provisional identity and first project for a new email without asking the user to choose a password or domain. The confirmation email is delivered through Resend and expires after 24 hours. The project grant can create multiple apps and expires after 24 hours.

If the email already exists, OpenCloud sends an approval request and withholds both the project and agent credential until the user submits that form. A GET of the email link only renders the review page; confirmation requires an explicit POST so mail-security link prefetchers cannot approve the request.

After confirmation, OpenCloud establishes the normal HttpOnly browser session. The agent never receives that browser session. The CLI keeps its grant in an ignored mode-0600 session file.

If the deadline passes before confirmation, OpenCloud revokes the provisional grant and pauses every app it created. HTTP runtime traffic, Functions, and cron stop. The app address shows a verification-required page with a Resend action, while data, files, deployments, secrets, and backups remain preserved. Submitting the verification form resumes all affected apps and active cron schedules.

Render the current user

const session = await opencloud.session();

if (!session) {
  renderSignedOut();
} else {
  renderIdentity({
    userId: session.userId,
    label:
      session.profile.displayName ??
      session.profile.email ??
      session.userId,
    expiresAt: session.sessionExpiresAt,
  });
}

The SDK keeps the access token private and refreshes through the HttpOnly broker cookie before refreshAfter. Never decode JWTs, copy access tokens into application state, or persist token material.

Public apps

A public app may have either an authenticated or anonymous visitor. Use session() to adapt the UI. REST requests are authenticated by default; pass auth: "anonymous" only when the RLS policy intentionally permits it. SDK 0.2.1 discovers a signed-out public visitor through a successful typed broker response, so null does not create an expected browser error.

Private authorization

Private app access is separate from identity. A valid OpenCloud account receives HTTP 403 when it has not been granted access to that app. The platform applies this edge check before serving the frontend or runtime APIs.

Session failures

• null in a public app is normal.
• null after a private app rendered indicates an expired or unavailable brokered session; show retry/sign-in UI.
• OpenCloudAuthError means an authenticated SDK operation cannot proceed.
• Never fall back to the anonymous mode for a user-private mutation.