Login and Token Flow

Every login flow around City converges to one goal:

get city_id + user_token into the city frontend, then enter normal User City calls.

Pattern one: your backend owns login

frontend submits login data
  -> your backend validates the account
  -> backend uses Admin City to request user_token
  -> returns city_id + user_token
  -> frontend creates a normal User City

Good fit when:

• you already have an account system
• you need more complex org, permission, or risk-control logic

Pattern two: the accounts service owns login

frontend creates a guest User City
  -> calls accounts.register / login
  -> service returns user_token
  -> frontend creates a normal User City

Good fit when:

• you want the fastest path to minimal registration and login
• you do not want to maintain your own user and session tables first

What a guest User City is

It is simply a User City with federation_url only:

const guest = new City({
  role: "user",
  federation_url: "https://base.example.com",
});

At this stage it is usually used only for guest-access Actions such as:

• accounts.register
• accounts.login
• accounts.oauth/start
• accounts.oauth/result

Switching to a normal User City

const user = new City({
  role: "user",
  federation_url: "https://base.example.com",
  city_id: "city_xxx",
  user_token: session.user_token,
});

At that point the city enters real user context:

• it can call AI services
• it can call custom services that require user identity
• it can call services such as accounts.me and usage.me