feat(billing): dedicated v2 usage endpoints; keep internal usage routes session-only

Replaces the earlier X-API-Key enablement on /api/users/me/usage-logs
with a dedicated public surface, so the internal Billing-settings
endpoints can evolve with the UI while external monitors get a stable
versioned contract:

- GET /api/v2/billing/usage — current-billing-period summary with
  bySourceCredits (the source breakdown external monitors need to watch
  e.g. Copilot consumption without estimating by subtraction), plus
  limitCredits and plan
- GET /api/v2/billing/usage/logs — cursor-paged credit ledger in the v2
  envelope
- workspace-scoped keys are pinned to their own workspace's slice;
  personal keys read the account ledger

The public wire is credits-only: usage-logs rows now carry a hasCost
boolean instead of dollarCost (the Billing UI only needed the >0
signal), and the rateLimit block is removed from the usage-limits
response and docs (deploy-modal tab relabeled accordingly).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CiHhAk2R1NryaS3R8n2yFz

Author: TheodoreSpeaks

apps/docs/openapi-core.json

@@ -2,11 +2,10 @@ import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { type NextRequest, NextResponse } from 'next/server'
 import { usageLimitsRequestSchema } from '@/lib/api/contracts/usage-limits'
-import { AuthType, checkHybridAuth } from '@/lib/auth/hybrid'
+import { checkHybridAuth } from '@/lib/auth/hybrid'
 import { checkServerSideUsageLimits } from '@/lib/billing'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/subscription'
 import { getUserStorageLimit, getUserStorageUsage } from '@/lib/billing/storage'
-import { RateLimiter } from '@/lib/core/rate-limiter'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { createErrorResponse } from '@/app/api/workflows/utils'
 
@@ -23,22 +22,6 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     const authenticatedUserId = auth.userId
 
     const userSubscription = await getHighestPrioritySubscription(authenticatedUserId)
-    const rateLimiter = new RateLimiter()
-    const triggerType = auth.authType === AuthType.API_KEY ? 'api' : 'manual'
-    const [syncStatus, asyncStatus] = await Promise.all([
-      rateLimiter.getRateLimitStatusWithSubscription(
-        authenticatedUserId,
-        userSubscription,
-        triggerType,
-        false
-      ),
-      rateLimiter.getRateLimitStatusWithSubscription(
-        authenticatedUserId,
-        userSubscription,
-        triggerType,
-        true
-      ),
-    ])
 
     const [usageCheck, storageUsage, storageLimit] = await Promise.all([
       checkServerSideUsageLimits(authenticatedUserId),
@@ -52,23 +35,6 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
 
     return NextResponse.json({
       success: true,
-      rateLimit: {
-        sync: {
-          isLimited: syncStatus.remaining === 0,
-          requestsPerMinute: syncStatus.requestsPerMinute,
-          maxBurst: syncStatus.maxBurst,
-          remaining: syncStatus.remaining,
-          resetAt: syncStatus.resetAt,
-        },
-        async: {
-          isLimited: asyncStatus.remaining === 0,
-          requestsPerMinute: asyncStatus.requestsPerMinute,
-          maxBurst: asyncStatus.maxBurst,
-          remaining: asyncStatus.remaining,
-          resetAt: asyncStatus.resetAt,
-        },
-        authType: triggerType,
-      },
       usage: {
         currentPeriodCost,
         limit: usageCheck.limit,

apps/sim/app/api/users/me/usage-limits/route.ts

@@ -2,18 +2,15 @@ import { createLogger } from '@sim/logger'
 import { type NextRequest, NextResponse } from 'next/server'
 import { exportUsageLogsContract } from '@/lib/api/contracts/user'
 import { parseRequest } from '@/lib/api/server'
-import { checkHybridAuth } from '@/lib/auth/hybrid'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import {
   getUsageCreditsByLogId,
   getUserUsageLogs,
   type UsageLogSource,
 } from '@/lib/billing/core/usage-log'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { formatCsvValue, toCsvRow } from '@/lib/table/export-format'
-import {
-  resolveDateRange,
-  resolveUsageLogsWorkspaceFilter,
-} from '@/app/api/users/me/usage-logs/shared'
+import { resolveDateRange } from '@/app/api/users/me/usage-logs/shared'
 import { USAGE_LOG_SOURCE_LABELS } from '@/app/api/users/me/usage-logs/source-labels'
 
 const logger = createLogger('UsageLogsExportAPI')
@@ -36,7 +33,7 @@ const CSV_HEADER = toCsvRow(['Date', 'Type', 'Credits'])
  * (unlike, say, a workspace's full execution history).
  */
 export const GET = withRouteHandler(async (request: NextRequest) => {
-  const auth = await checkHybridAuth(request, { requireWorkflowId: false })
+  const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
   if (!auth.success || !auth.userId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
@@ -45,13 +42,10 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
   if (!parsed.success) return parsed.response
   const { source, workspaceId, period, startDate, endDate } = parsed.data.query
 
-  const workspaceFilter = resolveUsageLogsWorkspaceFilter(auth, workspaceId)
-  if (!workspaceFilter.ok) return workspaceFilter.response
-
   const dateRange = resolveDateRange(period, startDate, endDate)
   const filter = {
     source: source as UsageLogSource | undefined,
-    workspaceId: workspaceFilter.workspaceId,
+    workspaceId,
     startDate: dateRange.startDate,
     endDate: dateRange.endDate,
   }

apps/sim/app/api/users/me/usage-logs/export/route.ts

@@ -1,7 +1,7 @@
 /**
  * @vitest-environment node
  */
-import { authMockFns, createMockRequest, hybridAuthMockFns } from '@sim/testing'
+import { authMockFns, createMockRequest } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { apportionCredits } from '@/lib/billing/credits/conversion'
 
@@ -46,58 +46,6 @@ describe('GET /api/users/me/usage-logs', () => {
     expect(response.status).toBe(401)
   })
 
-  it('accepts a personal API key and reads that user’s ledger unscoped', async () => {
-    hybridAuthMockFns.mockCheckHybridAuth.mockResolvedValueOnce({
-      success: true,
-      userId: 'key-owner',
-      authType: 'api_key',
-      apiKeyType: 'personal',
-    })
-
-    const response = await GET(createMockRequest('GET'))
-
-    expect(response.status).toBe(200)
-    expect(mockGetUserUsageLogs).toHaveBeenCalledWith(
-      'key-owner',
-      expect.objectContaining({ workspaceId: undefined })
-    )
-  })
-
-  it('pins a workspace API key to its own workspace’s slice of the ledger', async () => {
-    hybridAuthMockFns.mockCheckHybridAuth.mockResolvedValueOnce({
-      success: true,
-      userId: 'key-owner',
-      workspaceId: 'ws-1',
-      authType: 'api_key',
-      apiKeyType: 'workspace',
-    })
-
-    const response = await GET(createMockRequest('GET'))
-
-    expect(response.status).toBe(200)
-    expect(mockGetUserUsageLogs).toHaveBeenCalledWith(
-      'key-owner',
-      expect.objectContaining({ workspaceId: 'ws-1' })
-    )
-  })
-
-  it('rejects a workspace API key asking for a different workspace', async () => {
-    hybridAuthMockFns.mockCheckHybridAuth.mockResolvedValueOnce({
-      success: true,
-      userId: 'key-owner',
-      workspaceId: 'ws-1',
-      authType: 'api_key',
-      apiKeyType: 'workspace',
-    })
-
-    const response = await GET(
-      createMockRequest('GET', undefined, {}, 'http://localhost:3000/api/test?workspaceId=ws-2')
-    )
-
-    expect(response.status).toBe(403)
-    expect(mockGetUserUsageLogs).not.toHaveBeenCalled()
-  })
-
   it('converts dollar costs to credits in the logs and summary', async () => {
     const response = await GET(createMockRequest('GET'))
     const body = await response.json()
@@ -109,7 +57,7 @@ describe('GET /api/users/me/usage-logs', () => {
         source: 'workflow',
         workflowName: null,
         creditCost: 100,
-        dollarCost: 0.5,
+        hasCost: true,
       },
     ])
     expect(body.summary).toEqual({

apps/sim/app/api/users/me/usage-logs/route.test.ts

@@ -2,32 +2,25 @@ import { createLogger } from '@sim/logger'
 import { type NextRequest, NextResponse } from 'next/server'
 import { getUsageLogsContract } from '@/lib/api/contracts/user'
 import { parseRequest } from '@/lib/api/server'
-import { checkHybridAuth } from '@/lib/auth/hybrid'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import {
   getUsageCreditsByLogId,
   getUserUsageLogs,
   type UsageLogSource,
 } from '@/lib/billing/core/usage-log'
 import { dollarsToCredits } from '@/lib/billing/credits/conversion'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import {
-  resolveDateRange,
-  resolveUsageLogsWorkspaceFilter,
-} from '@/app/api/users/me/usage-logs/shared'
+import { resolveDateRange } from '@/app/api/users/me/usage-logs/shared'
 
 const logger = createLogger('UsageLogsAPI')
 
 /**
  * Lists the authenticated user's credit-consuming usage events (model, tool,
  * and fixed charges), converted to credits for display in Billing settings.
- *
- * Accepts session auth AND `X-API-Key` (matching `/api/users/me/usage-limits`,
- * whose aggregate `currentPeriodCost` this endpoint's `summary` breaks down by
- * source) so external monitors can watch e.g. Copilot consumption. Workspace
- * keys are pinned to their own workspace's slice of the ledger.
+ * Session-only — the API-key-facing equivalent is `GET /api/v2/billing/usage/logs`.
  */
 export const GET = withRouteHandler(async (request: NextRequest) => {
-  const auth = await checkHybridAuth(request, { requireWorkflowId: false })
+  const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
   if (!auth.success || !auth.userId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
@@ -37,14 +30,11 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
   const { source, workspaceId, period, startDate, endDate, limit, cursor, includeCredits } =
     parsed.data.query
 
-  const workspaceFilter = resolveUsageLogsWorkspaceFilter(auth, workspaceId)
-  if (!workspaceFilter.ok) return workspaceFilter.response
-
   const dateRange = resolveDateRange(period, startDate, endDate)
 
   const filter = {
     source: source as UsageLogSource | undefined,
-    workspaceId: workspaceFilter.workspaceId,
+    workspaceId,
     startDate: dateRange.startDate,
     endDate: dateRange.endDate,
   }
@@ -62,7 +52,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     source: log.source,
     workflowName: log.workflowName ?? null,
     creditCost: creditsByLogId[log.id] ?? 0,
-    dollarCost: log.cost,
+    hasCost: log.cost > 0,
   }))
 
   const bySourceCredits = Object.fromEntries(

apps/sim/app/api/users/me/usage-logs/route.ts

@@ -1,38 +1,7 @@
-import { NextResponse } from 'next/server'
 import type { UsageLogPeriod } from '@/lib/api/contracts/user'
-import type { AuthResult } from '@/lib/auth/hybrid'
 
 const PERIOD_TO_DAYS: Record<'1d' | '7d' | '30d', number> = { '1d': 1, '7d': 7, '30d': 30 }
 
-type WorkspaceFilterResult =
-  | { ok: true; workspaceId: string | undefined }
-  | { ok: false; response: NextResponse }
-
-/**
- * Resolves the effective `workspaceId` ledger filter for the caller's
- * credential. Sessions, internal JWTs, and personal API keys read the
- * authenticated user's full ledger with whatever filter they asked for; a
- * workspace-scoped API key is pinned to its own workspace — the filter
- * defaults to the key's workspace and an explicit mismatch is rejected rather
- * than silently ignored.
- */
-export function resolveUsageLogsWorkspaceFilter(
-  auth: AuthResult,
-  requestedWorkspaceId: string | undefined
-): WorkspaceFilterResult {
-  if (auth.apiKeyType !== 'workspace') return { ok: true, workspaceId: requestedWorkspaceId }
-  if (requestedWorkspaceId && requestedWorkspaceId !== auth.workspaceId) {
-    return {
-      ok: false,
-      response: NextResponse.json(
-        { error: 'API key is not authorized for this workspace' },
-        { status: 403 }
-      ),
-    }
-  }
-  return { ok: true, workspaceId: auth.workspaceId }
-}
-
 interface ResolvedDateRange {
   startDate: Date | undefined
   endDate: Date

apps/sim/app/api/users/me/usage-logs/shared.ts

@@ -44,6 +44,7 @@ export type ApiEndpoint =
   | 'knowledge-detail'
   | 'knowledge-search'
   | 'copilot-chat'
+  | 'billing-usage'
 
 export interface RateLimitResult {
   allowed: boolean