Login and Token Flow

Every login flow around City converges to one goal:

get user_token (which contains bureau_id) into the product frontend, then enter normal User City calls.

Pattern one: your backend owns login

frontend submits login data
  -> your backend validates the account
  -> backend uses FederationAdmin to request user_token
  -> returns user_token (which contains bureau_id)
  -> 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.providers
  -> calls accounts.login/start / continue / result or the registration flow by provider type
  -> login/result 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({
  federation_url: "https://base.example.com",
});

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

• accounts.register
• accounts.providers
• accounts.login/start
• accounts.login/continue
• accounts.login/result

Switching to a normal User City

const user = new City({
  federation_url: "https://base.example.com",
  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