Registration and Login

The most common register, login, and user_token-returning flow in @downcity/services.

AccountsService gives a downcity the shared account infrastructure, but email registration and login are available only when an email accounts provider is mounted and configured.

Before rendering an email form, ask the server which providers are enabled:

const providers = await guest.service("accounts").get("providers");

Render email registration or login only when the response contains an enabled email provider with type: "input". The form fields can come directly from that provider's inputs.

register

const registration = await guest.service("accounts").action("register").invoke({
  email: "[email protected]",
  password: "password123",
});

Complete email verification using the verification message before logging in. Registration does not deliver a User Token.

login

const start = await guest.service("accounts").action("login/start").invoke({
  provider: "email",
  client_type: "cli",
});

await guest.service("accounts").action("login/continue").invoke({
  login_id: start.login_id,
  login_secret: start.login_secret,
  input: {
    email: "[email protected]",
    password: "password123",
  },
});

const status = await guest.service("accounts").action("login/result").invoke({
  login_id: start.login_id,
  login_secret: start.login_secret,
});

// Retain this ID and reuse it if the exchange request must be retried.
const exchange_id = crypto.randomUUID();
if (status.status !== "done") throw new Error("Login is not ready");
const session = await guest.service("accounts").action("login/exchange").invoke({
  login_id: start.login_id,
  login_secret: start.login_secret,
  exchange_id,
});

User sessions

User sessions own identity, permissions, and Credits. City automatically carries optional city_id for logs, usage, and job source only. Business calls use federation.user.service(name) on the current Federation; administrators use a separate Session.

So it needs to know:

  • which downcity is currently being entered
  • which downcity context the token should be issued for

After login

Desktop and CLI save the complete session privately, including refresh credentials and expiration times. Bind the client to a host-owned resolver that coordinates renewal and returns the latest access credential:

const federation = new Federation({
  url: federation_url,
  user_token: session.user_token,
  resolve_user_token: read_current_access_token,
});

read_current_access_token(fetcher) renews when required and returns a token for this fixed session. See Login and Session for renewal, coordination, and logout. Never expose refresh credentials in logs or product UI.