@acarmisc/backstage-plugin-litellm-backend 0.19.0 → 0.21.0

package/dist/openapi.js

@@ -111,6 +111,7 @@ exports.openApiSpec = {
                                     team_id: { type: 'string' },
                                     duration: { type: 'string' },
                                     max_budget: { type: 'number', nullable: true, description: 'Positive number caps spend; null = unlimited' },
+                                    budget_duration: { type: 'string', description: 'How often max_budget resets (e.g. "30d", "1mo"); one of litellm.keys.allowedBudgetDurations' },
                                     tpm_limit: { type: 'number' },
                                     rpm_limit: { type: 'number' },
                                 } } } },
@@ -210,6 +211,27 @@ exports.openApiSpec = {
                 responses: { '200': { description: 'Team usage' }, '400': { description: 'Missing date range' } },
             },
         },
+        '/teams/{teamId}/usage/members': {
+            get: {
+                tags: ['Teams'],
+                summary: 'Per-member usage breakdown for a team',
+                description: 'Needs litellm.teamUsage.memberBreakdown.enabled. Allowed for team ' +
+                    'managers, members holding one of memberBreakdown.viewerRoles, and ' +
+                    'members granted litellm.team.usage.read. Spend is zeroed (with ' +
+                    'budget_hidden: true) under team budget hiding; spend_share_pct remains.',
+                parameters: [
+                    { name: 'teamId', in: 'path', required: true, schema: { type: 'string' } },
+                    { name: 'start_date', in: 'query', required: true, schema: { type: 'string' } },
+                    { name: 'end_date', in: 'query', required: true, schema: { type: 'string' } },
+                ],
+                responses: {
+                    '200': { description: 'One row per member, sorted by spend' },
+                    '400': { description: 'Missing date range' },
+                    '403': { description: 'Caller may see the team but not its member breakdown' },
+                    '404': { description: 'Feature disabled, or team not found / not visible to the caller' },
+                },
+            },
+        },
         '/usage': {
             get: {
                 tags: ['Usage'],

package/dist/opencode.d.ts

@@ -19,6 +19,11 @@ export interface OpencodeConfig {
     keyDuration: string;
     /** Default max budget (USD) for keys created via the connect flow. Default 50. */
     maxBudget: number;
+    /**
+     * Reset period of maxBudget (e.g. "30d"). Unset: maxBudget covers the key's whole life,
+     * which runs out early on long-lived keys.
+     */
+    budgetDuration?: string;
     /**
      * When true, a team query parameter must reference a team the user is a
      * member of (or manage); otherwise the key is personal-only.

package/dist/opencode.js

@@ -7,6 +7,7 @@ function readOpencodeConfig(config) {
         enabled,
         keyDuration: config.getOptionalString('litellm.opencode.keyDuration') ?? '30d',
         maxBudget: config.getOptionalNumber('litellm.opencode.maxBudget') ?? 50,
+        budgetDuration: config.getOptionalString('litellm.opencode.budgetDuration'),
         requireTeam: config.getOptionalBoolean('litellm.opencode.requireTeam') ?? false,
         metadata: config.getOptional('litellm.opencode.metadata') ?? {},
     };

package/dist/provisioning.d.ts

@@ -88,7 +88,20 @@ export declare class ProvisioningError extends Error {
     constructor(message: string, hint: string, provisioning: boolean, status?: number);
 }
 /**
- * Ensures the LiteLLM user exists, returning its UserInfo.
+ * The LiteLLM user id to act on for a computed id: the id of the user adopted
+ * by email for it, if any, else the computed id itself. Accurate once
+ * getOrProvisionUser or findLiteLLMUser has run for that id.
+ */
+export declare function effectiveUserId(userId: string): string;
+/**
+ * Finds the LiteLLM user for a Backstage identity without creating it: by
+ * the computed id first, then by the catalog email (see adoptUserByEmail).
+ * Returns null when neither matches.
+ */
+export declare function findLiteLLMUser(client: LiteLLMClient, tokenEntityRef: string | undefined, userId: string, catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<UserInfo | null>;
+/**
+ * Ensures the LiteLLM user exists, returning its UserInfo. The user may have
+ * been found by email under a different id: see effectiveUserId.
  * When the user is missing and provisioning is enabled, attempts to create it.
  * When provisioning is disabled, throws a ProvisioningError with a clear message.
  */

package/dist/provisioning.js

@@ -9,6 +9,8 @@ exports.resolveUserId = resolveUserId;
 exports.resolveCredentials = resolveCredentials;
 exports.resolveUserProfile = resolveUserProfile;
 exports.provisionUser = provisionUser;
+exports.effectiveUserId = effectiveUserId;
+exports.findLiteLLMUser = findLiteLLMUser;
 exports.getOrProvisionUser = getOrProvisionUser;
 exports.isUserMemberOfGroup = isUserMemberOfGroup;
 exports.resolveUserRole = resolveUserRole;
@@ -250,7 +252,68 @@ class ProvisioningError extends Error {
 }
 exports.ProvisioningError = ProvisioningError;
 /**
- * Ensures the LiteLLM user exists, returning its UserInfo.
+ * Computed user id → id of an existing LiteLLM user adopted by email. Saves
+ * the catalog and `/user/list` round-trips on later requests; an entry is
+ * dropped when the adopted user disappears.
+ */
+const adoptedUserIds = new Map();
+/**
+ * The LiteLLM user id to act on for a computed id: the id of the user adopted
+ * by email for it, if any, else the computed id itself. Accurate once
+ * getOrProvisionUser or findLiteLLMUser has run for that id.
+ */
+function effectiveUserId(userId) {
+    return adoptedUserIds.get(userId) ?? userId;
+}
+/**
+ * Looks the user up by the computed id, or by an id previously adopted for it.
+ */
+async function getUserByIdOrAdopted(client, userId) {
+    const adopted = adoptedUserIds.get(userId);
+    if (adopted) {
+        const info = await client.getUserInfo(adopted);
+        if (info)
+            return info;
+        adoptedUserIds.delete(userId);
+    }
+    return client.getUserInfo(userId);
+}
+/**
+ * Finds an existing LiteLLM user with the given email and remembers it for
+ * the computed id. Users created outside Backstage (or before
+ * `userIdDomain` was set) often have the email as their id; LiteLLM then
+ * refuses a second user with the same email, so the record must be adopted
+ * rather than created. `getUserByEmail` only returns exact email matches.
+ */
+async function adoptUserByEmail(client, userId, email, logger) {
+    if (!email)
+        return null;
+    const byEmail = await client.getUserByEmail(email);
+    if (!byEmail?.user_id)
+        return null;
+    if (byEmail.user_id !== userId) {
+        logger.info(`Found existing LiteLLM user ${byEmail.user_id} by email ${email}, reusing for ${userId}`);
+        adoptedUserIds.set(userId, byEmail.user_id);
+    }
+    return byEmail;
+}
+/**
+ * Finds the LiteLLM user for a Backstage identity without creating it: by
+ * the computed id first, then by the catalog email (see adoptUserByEmail).
+ * Returns null when neither matches.
+ */
+async function findLiteLLMUser(client, tokenEntityRef, userId, catalogClient, auth, logger) {
+    const existing = await getUserByIdOrAdopted(client, userId);
+    if (existing)
+        return existing;
+    if (!tokenEntityRef)
+        return null;
+    const profile = await resolveUserProfile(tokenEntityRef, catalogClient, auth, logger);
+    return adoptUserByEmail(client, userId, profile.email, logger);
+}
+/**
+ * Ensures the LiteLLM user exists, returning its UserInfo. The user may have
+ * been found by email under a different id: see effectiveUserId.
  * When the user is missing and provisioning is enabled, attempts to create it.
  * When provisioning is disabled, throws a ProvisioningError with a clear message.
  */
@@ -258,30 +321,31 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
     if (!userId) {
         throw new ProvisioningError('User not found in LiteLLM', 'No user identity could be resolved from the request.', provisioningEnabled);
     }
-    const existing = await client.getUserInfo(userId);
+    const existing = await getUserByIdOrAdopted(client, userId);
     if (existing) {
         return existing;
     }
-    if (!provisioningEnabled) {
-        throw new ProvisioningError('User not found in LiteLLM', 'Enable litellm.provisioning.enabled in app-config.yaml or create the user manually', false);
-    }
     // Single-flight: if another request for the same userId is already
-    // provisioning, await its result instead of starting a new /user/new.
-    // This collapses the /keys + /teams + /usage page-load thundering
-    // herd into a single LiteLLM round-trip.
+    // resolving or provisioning, await its result instead of starting a new
+    // lookup and /user/new. This collapses the /keys + /teams + /usage
+    // page-load thundering herd into a single LiteLLM round-trip.
     const pending = provisioningInFlight.get(userId);
     if (pending) {
         logger.info(`LiteLLM provisioning already in flight for ${userId} — joining`);
         return pending;
     }
     const provisionPromise = (async () => {
-        const catalogRef = tokenEntityRef ?? userId;
-        const [matchedRole, profile] = await Promise.all([
-            resolveUserRole(catalogRef, roleConfigs, catalogClient, auth, logger),
-            tokenEntityRef
-                ? resolveUserProfile(tokenEntityRef, catalogClient, auth, logger)
-                : Promise.resolve({}),
-        ]);
+        const profile = tokenEntityRef
+            ? await resolveUserProfile(tokenEntityRef, catalogClient, auth, logger)
+            : {};
+        const byEmail = await adoptUserByEmail(client, userId, profile.email, logger);
+        if (byEmail) {
+            return byEmail;
+        }
+        if (!provisioningEnabled) {
+            throw new ProvisioningError('User not found in LiteLLM', 'Enable litellm.provisioning.enabled in app-config.yaml or create the user manually', false);
+        }
+        const matchedRole = await resolveUserRole(tokenEntityRef ?? userId, roleConfigs, catalogClient, auth, logger);
         const effectiveDefaults = matchedRole
             ? applyRoleOverrides(provisioningDefaults, matchedRole)
             : provisioningDefaults;
@@ -299,11 +363,13 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
             // The single-flight cache should prevent the parallel-409 race,
             // but keep the recovery path: if /user/new still 409s (e.g.
             // multi-replica deploys where the lock is per-process), treat
-            // it as "user exists" and re-fetch.
+            // it as "user exists" and re-fetch, by id and then by email
+            // (LiteLLM also refuses a second user with the same email).
             if ((err instanceof client_1.LiteLLMUpstreamError && err.status === 409) ||
                 (err instanceof Error && /already exists/i.test(err.message ?? ''))) {
                 logger.info(`LiteLLM user ${userId} already exists during provisioning — re-fetching`);
-                const refetched = await client.getUserInfo(userId);
+                const refetched = (await client.getUserInfo(userId)) ??
+                    (await adoptUserByEmail(client, userId, profile.email, logger));
                 if (refetched) {
                     return refetched;
                 }

package/dist/router.js

@@ -46,6 +46,7 @@ const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-li
 const teamAdmin_1 = require("./teamAdmin");
 const teamBudgetVisibility_1 = require("./teamBudgetVisibility");
 const opencode_1 = require("./opencode");
+const teamMemberUsage_1 = require("./teamMemberUsage");
 const errors_2 = require("./errors");
 const withUser_1 = require("./routes/middleware/withUser");
 const userInfoCache_1 = require("./services/userInfoCache");
@@ -90,12 +91,15 @@ async function createRouter(options) {
         maxTpm: keyMaxTpm,
         maxRpm: keyMaxRpm,
         allowedDurations: keyAllowedDurations,
+        allowedBudgetDurations: config.getOptionalStringArray('litellm.keys.allowedBudgetDurations') ??
+            backstage_plugin_litellm_common_1.DEFAULT_KEY_BUDGET_DURATIONS,
     };
     const teamMgmtEnabled = (0, teamAdmin_1.isTeamManagementEnabled)(config);
     const objectPermsEnabled = (0, teamAdmin_1.isObjectPermissionsEnabled)(config);
     const teamAdminCfg = (0, teamAdmin_1.readTeamAdminConfig)(config);
     const teamBudgetVisibility = (0, teamBudgetVisibility_1.readTeamBudgetVisibility)(config);
     const opencodeCfg = (0, opencode_1.readOpencodeConfig)(config);
+    const memberBreakdownCfg = (0, teamMemberUsage_1.readMemberBreakdownConfig)(config);
     const catalogClient = options.catalogClient ?? new catalog_client_1.CatalogClient({ discoveryApi: discovery });
     if (provisioningEnabled) {
         logger.info(`LiteLLM auto-provisioning enabled — defaults: budget=$${provisioningDefaults.maxBudget}/${provisioningDefaults.budgetDuration}, models=${provisioningDefaults.models.length
@@ -109,8 +113,16 @@ async function createRouter(options) {
         teamBudgetVisibility.hideTeamBudgetForManagers) {
         logger.info(`LiteLLM team budget hiding enabled — members: ${teamBudgetVisibility.hideTeamBudgetForMembers}, managers: ${teamBudgetVisibility.hideTeamBudgetForManagers}`);
     }
+    // LiteLLM user id of a Backstage user: the computed id, or the id of an
+    // existing user with the same catalog email.
+    const resolveMemberUserId = async (userEntityRef) => {
+        const computed = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        await (0, provisioning_1.findLiteLLMUser)(client, userEntityRef, computed, catalogClient, auth, logger);
+        return (0, provisioning_1.effectiveUserId)(computed);
+    };
     // Build shared RouterContext with config and helpers
     const ctx = {
+        resolveMemberUserId,
         client,
         catalogClient,
         auth,
@@ -133,6 +145,7 @@ async function createRouter(options) {
         teamAdminCfg,
         teamBudgetVisibility,
         opencodeCfg,
+        memberBreakdownCfg,
         // Helper functions - defined inline below this object
         authorizeKeyAction: async (req, keyId) => {
             // Express middleware should have populated req.res.locals with user info
@@ -140,7 +153,8 @@ async function createRouter(options) {
                 throw new errors_1.NotAllowedError('User identity not found in request');
             }
             const tokenEntityRef = req.res.locals.tokenEntityRef;
-            const userId = req.res.locals.userId;
+            // The LiteLLM user may exist under a different id, found by email.
+            const userId = await resolveMemberUserId(tokenEntityRef);
             const ownKeys = await client.listKeys(userId);
             const key = ownKeys.find(k => (k.token ?? k.key) === keyId);
             if (!key) {
@@ -265,7 +279,8 @@ async function createRouter(options) {
             // The permission framework still has the final say.
             if (teamRoleEligible) {
                 const actor = await (0, provisioning_1.resolveUserId)(req, auth);
-                const litellmUserId = actor && (0, provisioning_1.toLiteLLMUserId)(actor, userIdDomain);
+                const litellmUserId = actor &&
+                    (await resolveMemberUserId(actor));
                 const role = existing.members_with_roles?.find(m => m.user_id === litellmUserId)?.role;
                 if (actor &&
                     role &&

package/dist/routes/config.js

@@ -29,6 +29,9 @@ function registerConfigRoutes(router, ctx) {
                 readOnly: ctx.teamAdminCfg.readOnly,
                 memberManagerRoles: ctx.teamAdminCfg.memberManagerRoles,
             },
+            teamUsage: {
+                memberBreakdown: ctx.memberBreakdownCfg.enabled,
+            },
             display: {
                 hideTeamBudgetForMembers: ctx.teamBudgetVisibility.hideTeamBudgetForMembers,
                 hideTeamBudgetForManagers: ctx.teamBudgetVisibility.hideTeamBudgetForManagers,

package/dist/routes/context.d.ts

@@ -8,6 +8,7 @@ import { TeamAdminConfig } from '../teamAdmin';
 import type { KeyValidationConfig } from '@acarmisc/backstage-plugin-litellm-common';
 import { TeamBudgetVisibility } from '../teamBudgetVisibility';
 import { OpencodeConfig } from '../opencode';
+import { MemberBreakdownConfig } from '../teamMemberUsage';
 /**
  * Shared runtime context for all route handlers. Holds config-derived
  * constants, service clients, and helper functions needed by routes.
@@ -35,6 +36,12 @@ export interface RouterContext {
     teamAdminCfg: TeamAdminConfig;
     teamBudgetVisibility: TeamBudgetVisibility;
     opencodeCfg: OpencodeConfig;
+    memberBreakdownCfg: MemberBreakdownConfig;
+    /**
+     * LiteLLM user id of a Backstage user: the computed id, or the id of an
+     * existing LiteLLM user with the same catalog email.
+     */
+    resolveMemberUserId(userEntityRef: string): Promise<string>;
     authorizeKeyAction(req: Request, keyId: string): Promise<{
         tokenEntityRef: string;
         userId: string;

package/dist/routes/keys.js

@@ -35,8 +35,8 @@ function registerKeysRoutes(router, ctx) {
     });
     router.get('/keys', async (_req, res) => {
         try {
-            const userId = res.locals.userId;
             await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const userId = res.locals.userId;
             const keys = await client.listKeys(userId);
             res.json(keys);
         }
@@ -55,9 +55,9 @@ function registerKeysRoutes(router, ctx) {
                 sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyRevokePermission);
                 return;
             }
-            const userId = res.locals.userId;
             // Ensure the user is provisioned
             await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const userId = res.locals.userId;
             // Load the caller's keys
             const keys = await client.listKeys(userId);
             // Identify expired keys (expires_at in the past)

package/dist/routes/middleware/withUser.d.ts

@@ -11,6 +11,7 @@ export declare function createRequireUser(ctx: RouterContext): (req: Request, re
 /**
  * Helper to fetch and provision a user from res.locals (populated by requireUser middleware).
  * Returns the user info or throws ProvisioningError (which the caller must handle and respond to).
+ * Updates `res.locals.userId` to the resolved LiteLLM user id.
  *
  * This deduplicates the repeated pattern:
  *   const userInfo = await getProvisionedUser(...);

package/dist/routes/middleware/withUser.js

@@ -29,6 +29,7 @@ function createRequireUser(ctx) {
 /**
  * Helper to fetch and provision a user from res.locals (populated by requireUser middleware).
  * Returns the user info or throws ProvisioningError (which the caller must handle and respond to).
+ * Updates `res.locals.userId` to the resolved LiteLLM user id.
  *
  * This deduplicates the repeated pattern:
  *   const userInfo = await getProvisionedUser(...);
@@ -37,5 +38,8 @@ function createRequireUser(ctx) {
 async function getProvisionedUser(ctx, res) {
     const tokenEntityRef = res.locals.tokenEntityRef;
     const userId = res.locals.userId;
-    return (0, provisioning_1.getOrProvisionUser)(ctx.client, tokenEntityRef, userId, ctx.provisioningEnabled, ctx.provisioningDefaults, ctx.roleConfigs, ctx.catalogClient, ctx.auth, ctx.logger);
+    const userInfo = await (0, provisioning_1.getOrProvisionUser)(ctx.client, tokenEntityRef, userId, ctx.provisioningEnabled, ctx.provisioningDefaults, ctx.roleConfigs, ctx.catalogClient, ctx.auth, ctx.logger);
+    // The LiteLLM user may have been found by email under a different id.
+    res.locals.userId = (0, provisioning_1.effectiveUserId)(userId);
+    return userInfo;
 }

package/dist/routes/opencode.js

@@ -66,8 +66,8 @@ function registerOpencodeRoutes(router, ctx) {
                 sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyCreatePermission);
                 return null;
             }
-            const userId = (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain);
-            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+            const computedUserId = (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain);
+            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, computedUserId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
             // Optional team binding: must be one of the user's own teams.
             const teamId = (req.query.team || req.body.team);
             if (teamId) {
@@ -84,7 +84,7 @@ function registerOpencodeRoutes(router, ctx) {
                 res.status(400).json({ error: 'A team is required for this connection' });
                 return null;
             }
-            return { tokenEntityRef, userId, userInfo, teamId, redirectUri };
+            return { tokenEntityRef, userId: (0, provisioning_1.effectiveUserId)(computedUserId), userInfo, teamId, redirectUri };
         };
         router.get('/opencode/connect', async (req, res) => {
             try {
@@ -156,6 +156,7 @@ function registerOpencodeRoutes(router, ctx) {
                         alias,
                         duration: opencodeCfg.keyDuration,
                         max_budget: opencodeCfg.maxBudget,
+                        ...(opencodeCfg.budgetDuration && { budget_duration: opencodeCfg.budgetDuration }),
                         team_id: teamId,
                         metadata: {
                             ...opencodeCfg.metadata,
@@ -202,15 +203,18 @@ function registerOpencodeRoutes(router, ctx) {
                     res.status(502).json({ error: 'LiteLLM returned no key material' });
                     return;
                 }
+                logger.info('opencode.connect', { userId, team: teamId ?? null, rotated });
+                // The Backstage connect page calls this with fetchApi (JSON + Bearer) and does the
+                // loopback redirect itself, so it can collect one key per team in a single trip.
+                if (req.is('application/json')) {
+                    res.set('Cache-Control', 'no-store');
+                    res.json({ key, team: teamId ?? null });
+                    return;
+                }
                 const url = new URL(redirectUri);
                 url.searchParams.set('key', key);
                 if (teamId)
                     url.searchParams.set('team', teamId);
-                logger.info('opencode.connect', {
-                    userId,
-                    team: teamId ?? null,
-                    rotated,
-                });
                 res.redirect(302, url.href);
             }
             catch (error) {

package/dist/routes/teamUsage.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerTeamUsageRoutes = registerTeamUsageRoutes;
+const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
+const client_1 = require("../client");
 const provisioning_1 = require("../provisioning");
 const teamBudgetVisibility_1 = require("../teamBudgetVisibility");
+const teamMemberUsage_1 = require("../teamMemberUsage");
 const errors_1 = require("../errors");
 const teamFetch_1 = require("../http/teamFetch");
 const withUser_1 = require("./middleware/withUser");
@@ -69,4 +72,110 @@ function registerTeamUsageRoutes(router, ctx) {
             (0, errors_1.sendError)(res, error, logger, 'fetch team usage');
         }
     });
+    // Per-member breakdown of a team's usage. Opt-in (404 when disabled) and
+    // fail-closed: the caller must be a manager of the team (owning_group), or
+    // a member who holds one of memberBreakdown.viewerRoles in the team or is
+    // granted litellm.team.usage.read.
+    router.get('/teams/:teamId/usage/members', requireUser, async (req, res) => {
+        const cfg = ctx.memberBreakdownCfg;
+        if (!cfg.enabled) {
+            res.status(404).json({ error: 'Not found' });
+            return;
+        }
+        try {
+            const { teamId } = req.params;
+            const { start_date, end_date } = req.query;
+            if (!start_date || !end_date) {
+                res.status(400).json({ error: 'start_date and end_date are required' });
+                return;
+            }
+            const tokenEntityRef = res.locals.tokenEntityRef;
+            const userInfo = await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const callerId = res.locals.userId;
+            const isMember = userInfo?.teams?.includes(teamId) ?? false;
+            let team;
+            try {
+                team = await (0, teamFetch_1.withTeamFetchRetry)(() => client.getTeamInfo(teamId));
+            }
+            catch (err) {
+                if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
+                    res.status(404).json({ error: 'Team not found' });
+                    return;
+                }
+                throw err;
+            }
+            const owningGroup = typeof team.metadata?.owning_group === 'string' ? team.metadata.owning_group : undefined;
+            const isManager = ctx.teamMgmtEnabled &&
+                !!owningGroup &&
+                (await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, owningGroup, catalogClient, auth, logger));
+            if (!isMember && !isManager) {
+                res.status(404).json({ error: 'Team not found' });
+                return;
+            }
+            const role = team.members_with_roles?.find(m => m.user_id === callerId)?.role;
+            const viaRole = isMember && !!role && cfg.viewerRoles.includes(role);
+            const allowed = isManager ||
+                viaRole ||
+                (isMember &&
+                    cfg.permissionEnabled &&
+                    (await ctx.assertPermission(req, backstage_plugin_litellm_common_1.litellmTeamUsageReadPermission)));
+            if (!allowed) {
+                res.status(403).json({
+                    error: 'Access denied: viewing per-member usage needs a team role or permission',
+                });
+                return;
+            }
+            const [usage, keys] = await Promise.all([
+                client.getTeamUsage(teamId, start_date, end_date),
+                client.listTeamKeys(teamId),
+            ]);
+            const profiles = await lookupProfiles((0, teamMemberUsage_1.memberEmails)(team, keys));
+            const breakdown = (0, teamMemberUsage_1.buildTeamMemberUsage)(teamId, usage, keys, team, profiles);
+            let via = 'permission';
+            if (isManager)
+                via = 'manager';
+            else if (viaRole)
+                via = 'teamRole';
+            logger.info('team.usage.members.read', { actor: tokenEntityRef, teamId, via });
+            const hide = isManager
+                ? teamBudgetVisibility.hideTeamBudgetForManagers
+                : teamBudgetVisibility.hideTeamBudgetForMembers;
+            res.json(hide ? (0, teamMemberUsage_1.redactTeamMemberUsage)(breakdown) : breakdown);
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'fetch team member usage');
+        }
+    });
+    // Display names from catalog User entities with these emails. Best effort:
+    // a catalog failure only drops the names.
+    async function lookupProfiles(emails) {
+        const profiles = new Map();
+        if (!emails.length)
+            return profiles;
+        try {
+            const { token } = await auth.getPluginRequestToken({
+                onBehalfOf: await auth.getOwnServiceCredentials(),
+                targetPluginId: 'catalog',
+            });
+            const { items } = await catalogClient.getEntities({
+                filter: { kind: 'User', 'spec.profile.email': emails },
+                fields: ['spec.profile'],
+            }, { token });
+            for (const entity of items) {
+                const profile = entity.spec?.profile ?? {};
+                if (typeof profile.email === 'string') {
+                    profiles.set(profile.email.toLowerCase(), { displayName: profile.displayName });
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`Catalog lookup for team member names failed: ${message}`);
+        }
+        return profiles;
+    }
 }

package/dist/routes/teams.js

@@ -306,9 +306,9 @@ function registerTeamsRoutes(router, ctx) {
             return;
         }
         // (b) the member must exist in LiteLLM — provision on the spot if enabled
-        const litellmUserId = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        const computedUserId = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
         try {
-            await (0, provisioning_1.getOrProvisionUser)(client, userEntityRef, litellmUserId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+            await (0, provisioning_1.getOrProvisionUser)(client, userEntityRef, computedUserId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
         }
         catch (err) {
             if (err instanceof provisioning_1.ProvisioningError) {
@@ -317,6 +317,8 @@ function registerTeamsRoutes(router, ctx) {
             }
             throw err;
         }
+        // The member may exist under a different id, found by email.
+        const litellmUserId = (0, provisioning_1.effectiveUserId)(computedUserId);
         try {
             await client.teamMemberAdd({
                 team_id: teamId,
@@ -355,11 +357,11 @@ function registerTeamsRoutes(router, ctx) {
                 .json({ error: 'userEntityRef query parameter is required' });
             return;
         }
-        const litellmUserId = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        const litellmUserId = await ctx.resolveMemberUserId(userEntityRef);
         // Team-role managers change membership only: they cannot remove
         // themselves nor a peer holding a manager role.
         if (via === 'teamRole') {
-            if (litellmUserId === (0, provisioning_1.toLiteLLMUserId)(actor, userIdDomain)) {
+            if (litellmUserId === (await ctx.resolveMemberUserId(actor))) {
                 res.status(400).json({ error: 'You cannot remove yourself from the team' });
                 return;
             }

package/dist/services/keyService.js

@@ -124,6 +124,9 @@ async function createKeyForUser(user, input, ctx) {
         // max_budget from input can be null (unlimited) or a number
         upstreamRequest.max_budget = input.max_budget ?? undefined;
     }
+    if (input.budget_duration !== undefined) {
+        upstreamRequest.budget_duration = input.budget_duration;
+    }
     if (input.tpm_limit !== undefined) {
         upstreamRequest.tpm_limit = input.tpm_limit;
     }

package/dist/teamMemberUsage.d.ts

@@ -0,0 +1,34 @@
+import { Config } from '@backstage/config';
+import { TeamInfo, TeamMemberUsage, UsageMetrics, VirtualKey } from './types';
+/** `litellm.teamUsage.memberBreakdown`: who may see a team's per-member usage. */
+export interface MemberBreakdownConfig {
+    /** Off by default: the route returns 404 and the UI hides the table. */
+    enabled: boolean;
+    /** LiteLLM team roles (e.g. "admin") whose holders may view their own team's breakdown. */
+    viewerRoles: string[];
+    /** Whether `litellm.team.usage.read` may grant access (needs `permission.enabled`). */
+    permissionEnabled: boolean;
+}
+export declare function readMemberBreakdownConfig(config: Config): MemberBreakdownConfig;
+/** Catalog profile of a member, keyed by lower-cased email. */
+export type MemberProfiles = Map<string, {
+    displayName?: string;
+}>;
+/**
+ * Emails worth looking up in the catalog for the members of a breakdown:
+ * the team roster's emails and email-shaped user ids.
+ */
+export declare function memberEmails(team: TeamInfo, keys: VirtualKey[]): string[];
+/**
+ * Attributes a team's usage to its members. Each key in the team's daily
+ * activity is credited to the key's owner (from `/key/list?team_id=`), so the
+ * rows add up to the team total. Activity of keys with no known owner
+ * (deleted keys, keys without a user) lands in one `user_id: null` row.
+ * Team members without activity get zero rows.
+ */
+export declare function buildTeamMemberUsage(teamId: string, usage: UsageMetrics, keys: VirtualKey[], team: TeamInfo, profiles?: MemberProfiles): TeamMemberUsage;
+/**
+ * Hides dollar amounts: spend becomes 0 and `spend_share_pct` remains the
+ * way to compare members. Tokens and requests are kept.
+ */
+export declare function redactTeamMemberUsage(usage: TeamMemberUsage): TeamMemberUsage;