Governance and alerts

Create a key

1. Open Governance › Keys and choose Create key.
2. Enter a Name (for example prod-api), and optionally an Environment and a Team.
3. Choose Create key and copy the key. It is shown once; only its prefix and a hash are kept.

The table shows each key's prefix, environment and team, Created, Last seen, Expires and status (live, revoked or expired).

Rotate without downtime

Choose Actions › Rotate on a live key. Token Meter mints a second live key under the same name, with the same environment and team. Both keys work until you revoke the old one, so you can roll the new key out first. A name can have at most two live keys; to rotate again, revoke the older one first.

Revoke

Choose Actions › Revoke and type the key's name to confirm. The key stops working straight away and cannot be restored: the SDK gets 401, and Router and preflight calls made with it are refused.

Read API keys

Owners and admins can also create read keys with Create read key. A read key can only read daily usage summaries from /api/v1/usage/daily; it cannot send or change usage. Keep read keys separate from ingest keys. See the Read API reference.

Create a policy

1. Choose Add policy.
2. Enter a Policy Name.
3. Choose a Team Scope (Global (All Teams), or one team) and an Environment (All Environments, Production, Staging or Development).
4. Pick any of:
   • Allowed Models: only these models may be used. Leave empty to allow all.
   • Blocked Models: these models may not be used.
   • Providers: click a provider once to allow only the providers marked green, twice to block it (red), a third time to clear it.
   • Blocked Data Classes: requests that carry any of these classes are refused.
   • Max Tokens / Request and Max Cost / Request (USD).
5. Set the Violation Severity (low, medium, high or critical; high by default) and an optional Owner Email, which are copied onto every violation of this policy.
6. Optionally tick Revoke credentials on detected violations (see Automatic credential revocation).
7. Choose Create Policy.

Each policy is listed with its scope, models, guardrails, violations in the last 30 days and status. Click the status to switch a policy between Active and Disabled, or delete it with Delete.

How policies apply

• Every active policy whose scope matches a request applies to it. When several set a token or cost cap, the tightest one wins.
• A team-scoped policy matches the request's team tag against the team's slug. A request without a team tag never matches a team-scoped policy, and the same goes for environment.
• Model rules match a model and its dated snapshots, never a substring.
• Data classes: a family name covers its members, so blocking pii also blocks pii.email, pii.phone and pii.us_ssn. The Router and preflight detect email addresses, phone numbers, US social security numbers, card numbers, API keys, AWS access keys and private keys in the prompt. A caller can also declare a class (public, internal, confidential, restricted, pii, phi or pci) with data_classification; that is the only way business labels such as restricted or phi are known. Only the class labels are kept, never the matched text.
• Separately from policies, ingest scans event metadata (feature, customer reference and tag values) for things like email addresses, phone numbers, card numbers and API keys, and redacts them before storage. Governance › Guardrails links to what was redacted, under Analytics › Use cases.

Where policies are enforced

Before a call, the Router checks the final provider and model (after tiering and any fallback), the data classes in the prompt plus any declared ones, the worst-case token count (input plus the output limit) and its estimated cost. After a call, ingest checks the provider, model, actual tokens, reported cost and any class declared on the event in tags.data_classification; it never sees the prompt.

If the Router cannot read your policies, it refuses the call with 503 and governance_policies_unavailable rather than letting it through.

For calls your code makes directly to a provider, governance preflight asks the Router before the call under the same policies. It adds one round trip and can stop the call.

Enforcement coverage

The share of your AI requests over a recent window, per provider:

• Routed: enforced before the call by the Router.
• Preflight-protected: a direct call cleared by preflight first.
• Detected after the fact: reported by the SDK, OpenTelemetry or connectors, checked only after the provider was called.
• Unknown: usage the provider reported that never appeared in metered events. This is only measurable for providers with a connected admin key.

Policy violations

Each violation shows where it was caught, the policy (or provider control), its scope, team and environment, project and key, owner, how many times and when it was seen, the remediation done and its status. Repeats of the same block within the same hour, or of the same detection on the same day, add to one violation's count instead of creating new ones.

Open a violation to Resolve, Acknowledge or Dismiss it, or Reopen a closed one. The list shows Open & acknowledged by default; switch to All for the history.

What happens on a detected violation

A job runs every minute and, for each new detected violation:

1. Alert. If its severity is at or above Alert at severity (medium until you change it), an alert is raised and delivered to the channels on your workspace-wide Governance violation (detected) rule. A critical violation becomes a Critical alert, low becomes Info, and medium and high become Warning. Without that rule the alert shows on Monitors and in the Inbox but is sent nowhere.
2. Ticket webhook. If you set one, a signed JSON POST is sent (see below).
3. Revocation. Only if both the policy or provider control and the workspace allow it.

The violation's Remediation field shows each result: Alert sent or "below threshold / pending", the webhook status, and the revocation status with its target.

Set up detection and remediation

1. On Governance › Guardrails, choose Detection & remediation.
2. Pick Alert at severity.
3. Optionally enter a Ticket / incident webhook URL. It must be a public https:// address.
4. Optionally tick Allow automatic credential revocation.
5. Choose Save. When you saved a webhook URL, copy the signing secret now; it is shown once. Saving a new URL issues a new secret.
6. If the dialog says there is no alert channel yet, create a Governance violation (detected) rule on Monitors (see Monitors and alert rules).

Ticket webhook

Each detected violation is sent once as a POST with a JSON body, for Jira or ServiceNow automation, PagerDuty, or anything that accepts JSON:

{
  "type": "governance.violation.detected",
  "violation": {
    "id": "<violation id>",
    "org_id": 123,
    "policy_id": "<policy id or null>",
    "control_id": "<provider control id or null>",
    "enforcement_point": "ingest",
    "kind": "model_not_allowed",
    "severity": "high",
    "owner_email": "team-lead@company.com",
    "team": "core-platform",
    "environment": "production",
    "provider": "openai",
    "model": "<model id>",
    "provider_key_id": null,
    "provider_project_id": null,
    "event_id": "<event id>",
    "reason": "<why it was flagged>",
    "occurrences": 1,
    "first_seen_at": "<ISO 8601 time>",
    "last_seen_at": "<ISO 8601 time>",
    "auto_revoke": false
  }
}

kind is one of model_blocked, model_not_allowed, provider_blocked, provider_not_allowed, data_classification, token_cap, cost_cap, unapproved_provider_project, unapproved_provider_key or unapproved_service_account. The body never contains prompt content or credentials.

Every request carries X-TokenMeter-Timestamp (Unix seconds) and X-TokenMeter-Signature: v1=<hex>, where the hex is HMAC-SHA256 of <timestamp>.<raw body> with your signing secret. Verify it before trusting the body:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySignature(rawBody: string, timestamp: string, signature: string, secret: string): boolean {
  const expected = "v1=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Any 2xx response counts as delivered. Redirects are not followed, the URL is checked again before every send, each attempt times out after 5 seconds, and a failed delivery is retried up to three attempts in all. To stop sending, tick Remove the configured webhook and save.

Provider-side enforcement

Traffic that never reaches Token Meter cannot be blocked by it. Provider-side enforcement on Guardrails generates an AWS Organizations SCP for Bedrock and an Azure Policy for Azure OpenAI from your workspace-wide policies (those with no team or environment scope). Review them before you apply them: wildcard ARNs and Azure aliases can match more than the exact model names.

Create a budget

1. Choose New policy.
2. Enter a Policy name.
3. Pick Applies to (scope) and, unless it is org, a Scope target value exactly as it appears in your usage tags (for example a team slug or customer reference). Leave the value blank to cover the whole scope.
4. Enter the Budget / month (USD).
5. Pick the Enforcement mode: Advisory, or Enforced on router traffic (workspace-wide budgets only).
6. Set Trigger thresholds as percentages of the budget, comma separated (50,80,100 by default; left empty, 80 and 100).
7. Leave Also alert on projected overrun (linear burn) ticked to be warned early.
8. Tick the channels under Notify via. A budget without a channel still tracks spend but notifies nobody.
9. Choose Create policy.

What happens as spend grows

Budgets are checked every 60 seconds against month-to-date spend for the UTC calendar month, from every connected usage source.

• Each threshold fires once per month: a Critical alert at 100% or more, a Warning below that.
• The projection alert is a Warning raised when month-to-date spend, divided by the days elapsed and multiplied by the days in the month, is over the budget.
• Each budget card shows spend against the cap, its channels and a status: Over cap at 100% or more, At risk from its lowest threshold under 100% (80% if it has none), On track below that, or Silenced. For an enforced budget the status follows the Router's count (see below). Triggered now lists the budgets that are At risk or Over cap.
• From a card's menu: Silence stops checking it (and enforcing it) until you choose Enable; Enforce on router or Make advisory switches the mode of a workspace-wide budget; Delete removes it.

Enforced budgets

An enforced budget caps traffic that goes through the router. The Router keeps its own count of router spend against the cap (shown on the card as "Router: ... incl. reserved"). Before each routed call it reserves the call's estimated cost:

1. If the call fits in what is left, it goes ahead.
2. If not, the Router tries the fallback model set in Routing settings, but only when a current model-downgrade recommendation for that model pair has passed its quality gate and the fallback is allowed by your policies.
3. Otherwise the call is refused with HTTP 402 and monthly_budget_exceeded.

Create a rule

1. Open Monitors › Rules and choose New rule.
2. Enter a Name and pick a Kind (below).
3. Fill in the fields that kind uses.
4. Tick the channels under Notify via.
5. Choose Create rule.

Rules are evaluated every 60 seconds. Each rule's row has Edit, Silence or Enable, and Delete.

The last four kinds only choose where those alerts go. Create them with Scope org, keep one rule per kind (with several, only one is used), and leave the amounts empty.

Threshold, budget and provider-spike alerts close by themselves when the condition clears; a Shadow AI alert closes when its finding is triaged. An alert never fires twice while it is open. Dedup window (minutes) (60 by default) is how long after an alert closes the same condition must wait before it can fire again.

Active alerts

The table lists status, severity, subject, the rule or budget, when it fired and, for anomalies, a link to the trace. Filter by severity, status, rule and provider over 7, 30 or 90 days; your plan may keep less history.

Delivery

• Every 60 seconds, each open alert raised in the last 24 hours is sent to every channel on its rule or budget that has not had it yet.
• Slack and Discord receive the alert's one-line subject. Email arrives with the subject "Token Meter alert: ..." and the same line as its body. Shadow AI alerts add a link to review the finding.
• A failed channel is retried after one minute and again after two, three attempts in all. An alert that closes before it is delivered is not sent.
• A silenced channel receives nothing. Use Silence and Enable to pause a channel without deleting it.

The Last delivery column shows "never attempted", "Delivered" with the time, or "Failed" with the time and the error (an HTTP status or network error; never the URL). Monitors and Settings both warn when a channel's last delivery failed.