---
id: CAP-PFM-LLM-014
title: Provide temporary AI capacity and revoke it
feature: FEAT-PFM-LLM-05
product_area: platform
module: llm
revision: 1
status: draft
product_intent: proposed
implementation_evidence: partially-observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-3'
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-4'
purpose: Let managers restore or exempt AI work for a stated period with an auditable reason.
outcomes:
  - Temporary grants can restore admission capacity.
  - The grant window determines when capacity applies.
  - Revocation preserves the original grant and records withdrawal.
concepts:
  - CON-PFM-LLM-003
actors:
  - ACT-PFM-004
  - ACT-PFM-007
surfaces:
  - api
  - console
preconditions:
  - An existing organization is selected.
postconditions:
  - Grant and revocation writes include their control audit.
permissions:
  - key: hq.llm-usage.manage
    where_checked: api
    scope: global
  - key: hq.llm-usage.manage
    where_checked: console
    scope: global
rules:
  - id: BR-CAP-PFM-LLM-014-01
    proved_by: [ATS-PFM-LLM-014-01, TST-PFM-LLM-008]
    statement: >-
      Grant, preview and revocation require the sensitive HQ usage manage key, excluding read-only staff and
      customer administrators; customer administrators also cannot list HQ grants.
    kind: permission
    enforced_at:
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-overrides.e2e.spec.js#is refused the grant before a handler
      runs, whatever the customer’s scope grants
    origin: none
  - id: BR-CAP-PFM-LLM-014-02
    proved_by: [ATS-PFM-LLM-013-10, ATS-PFM-LLM-014-02, ATS-PFM-LLM-014-15, TST-PFM-LLM-008, TST-PFM-LLM-026, TST-PFM-LLM-029, TST-PFM-LLM-071]
    statement: >-
      Additional-credit grants accept one to one million whole credits, while an operation exemption names one
      declared operation and carries no credits; invalid kinds, fields or values are rejected.
    kind: validation
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-03
    proved_by: [ATS-PFM-LLM-014-03, ATS-PFM-LLM-014-11, ATS-PFM-LLM-014-12, ATS-PFM-LLM-014-14, TST-PFM-LLM-010, TST-PFM-LLM-015, TST-PFM-LLM-029, TST-PFM-LLM-039]
    statement: >-
      The default grant begins now and ends at the next local month boundary; explicit windows must end after
      their start, end in the future and span no more than ninety-two days.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-04
    proved_by: [ATS-PFM-LLM-014-04, TST-PFM-LLM-029]
    statement: >-
      Grants require a trimmed reason of one to five hundred characters and accept an optional ticket
      reference of at most two hundred.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-05
    proved_by: [ATS-PFM-LLM-014-05, TST-PFM-LLM-029]
    statement: >-
      At every instant in a new grant window, base allowance and overlapping unrevoked capacity must fit under
      the one-thousand-dollar ceiling; sequential grants are separate and per-organization decisions are
      serialized.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-3'
  - id: BR-CAP-PFM-LLM-014-06
    proved_by: [ATS-PFM-LLM-014-06, TST-PFM-LLM-029]
    statement: >-
      The grant and widening audit event commit together with reason, ticket and window, while invalid grants
      write neither.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-07
    proved_by: [ATS-PFM-LLM-007-17, ATS-PFM-LLM-011-11, ATS-PFM-LLM-012-08, ATS-PFM-LLM-014-07, ATS-PFM-LLM-014-13, TST-PFM-LLM-019, TST-PFM-LLM-029, TST-PFM-LLM-038]
    statement: >-
      Revocation retains the original grant values and records actor, time and reason with a non-widening
      audit event; ended or revoked grants reject another revocation, and foreign grants are not found.
    kind: lifecycle
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-08
    proved_by: [ATS-PFM-LLM-014-08, TST-PFM-LLM-029]
    statement: >-
      When requested, a grant that restores a stopped organization emails its administrators after saving; a
      grant that restores nobody sends no message.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-4'
  - id: BR-CAP-PFM-LLM-014-09
    proved_by: [ATS-PFM-LLM-014-09, TST-PFM-LLM-029]
    statement: >-
      Preview uses grant validation and projects current and granted capacity, remaining credits, restoration
      and the peak allowance without creating records.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-10
    proved_by: []
    statement: 'Submitting the same grant twice creates and audits two grants, while a repeated revocation is refused.'
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: documented
    source: 'services-platform:docs/llm.md#Overrides'
    origin: none
  - id: BR-CAP-PFM-LLM-014-11
    proved_by: []
    statement: A failed capacity notice is logged and counted without retrying or undoing the grant.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: observed
    source: 'services-platform:modules/llm/services/notices/override-notice.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-014-12
    proved_by: []
    statement: Usage managers see a disabled Grant Override control in the console with an unavailable label.
    kind: permission
    enforced_at:
      - console
    must_prove: false
    provenance: observed
    source: 'react-console:components/console/hq/tenant-ai-usage-card.tsx:663'
    origin: none
scenarios:
  - id: SC-CAP-PFM-LLM-014-01
    given: The base allowance cannot admit another request.
    when: An active grant adds enough capacity.
    then: Admission succeeds with the grant included.
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/services/overrides/allowance-overrides.integration.spec.js#lets
      the ledger admit a call the base alone would refuse
  - id: SC-CAP-PFM-LLM-014-02
    given: A saved grant is active.
    when: An administrator revokes it with a reason.
    then: Revocation removes its future capacity and appears beside the grant in the audit.
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-overrides.e2e.spec.js#audits the revocation as a
      non-widening action beside the grant
edge_cases: []
constraints:
  - The console grant and revoke controls are incomplete.
depends_on:
  - CAP-PFM-LLM-007
related:
  - CAP-PFM-LLM-011
  - CAP-PFM-LLM-012
  - CAP-PFM-LLM-013
journeys:
  - JNY-PFM-LLM-003
open_questions: []
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (The predicate, and the
    overrides it reads; Overrides); docs/milestones/PLAT-M2-ai-usage-hq-controls.md;
    aws/api/llm-usage.routes.ts (grantHqTenantLlmUsageOverride, previewHqTenantLlmUsageOverride,
    revokeHqTenantLlmUsageOverride); services/overrides/allowance-overrides.ts;
    services/notices/override-notice.ts; db/llm-allowance-overrides.table.ts; tests
    e2e/llm-overrides.e2e.spec.js, integration/services/overrides/allowance-overrides.integration.spec.js,
    integration/db/llm-allowance-overrides.table.integration.spec.js,
    llm-overrides-migration.integration.spec.js, unit/services/allowance-overrides.spec.ts.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/hq/tenant-ai-usage-card.tsx
    (disabled Grant Override).
controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-LLM-05-01, FAS-PFM-LLM-05-02, FAS-PFM-LLM-05-03, FAS-PFM-LLM-05-04, FAS-PFM-LLM-05-05]
suites: [TST-PFM-LLM-008, TST-PFM-LLM-010, TST-PFM-LLM-015, TST-PFM-LLM-019, TST-PFM-LLM-026, TST-PFM-LLM-029, TST-PFM-LLM-038, TST-PFM-LLM-039, TST-PFM-LLM-071]
---

# Provide temporary AI capacity and revoke it

## Purpose

Let managers restore or exempt AI work for a stated period with an auditable reason.

## How It Works

A manager chooses additional credits or an exemption for one operation. Platform validates the grant window and checks the peak effective allowance over overlapping grants. Preview exposes the proposed position without storing a grant. A successful grant retains its reason, actor and any ticket reference alongside a widening audit event. Admission evaluates the grant’s active window directly. Managers revoke rather than edit grants so the original authorization remains visible. An optional capacity email applies only when the grant restores a stopped organization. The management API exists, while the console action remains disabled.

## Relationships

- Admit AI work against the organization’s monthly allowance supplies the prerequisite behavior for this outcome.