Understand Downcity City
Token Model
How `admin_secret_key` and `user_token` work together.
Downcity uses admin_secret_key to manage Federation, and user_token to let end-user clients call services.
Trusted backendYour backend uses Admin City and holds
admin_secret_key.Create city / request user_tokenDowncityValidates
admin_secret_key, issues user_token, and stores provider keys internally.End-user clientThe frontend, extension, or app only gets
user_token + city_id and uses User City to call services.No access to admin_secret_keyuser_token
user_token is the call credential used by the end user or product client. Admin City requests it from Federation using city_id + user_id.
city_iduser_idmetadatattl
The client only carries user_token and city_id. It never touches provider keys or admin_secret_key.
admin_secret_key
DOWNCITY_FEDERATION_ADMIN_SECRET_KEY is used to manage Federation: create cities, manage env, and issue user_token for users under a given city. Federation generates it automatically and writes it into Federation env on first startup.
const client = new City({
role: "admin",
federation_url: "https://base.example.com",
admin_secret_key: process.env.DOWNCITY_FEDERATION_ADMIN_SECRET_KEY,
});
const city = await client.cities.create({
name: "Chrome Extension",
});Multi-city reuse
Many clients can belong to the same city. When issuing a token, write city_id explicitly:
const user = await client.cities.tokens.apply({
city_id: city.city_id,
user_id: "user_123",
metadata: {
plan: "pro",
},
ttl: "7d",
});
console.log(user.user_token);