Management API

Management endpoints let agents self-provision standard keys and manage account operations with a provisioning key.

• Base URL: https://api.truval.dev
• Prefix: /v1/management/*
• Auth: Authorization: Bearer sk_mgmt_...

Provisioning keys are created once in the dashboard and should be stored securely.

OpenAPI Specification

https://api.truval.dev/openapi.json

Endpoints

GET /v1/management/account

Returns account tier, billing state, limits, and usage_this_month: verify-API free-tier monthly quota semantics for the current UTC month (same exclusions as public count_usage_for_customer — throttle and monthly-quota-only rows remain in usage_log but are not counted here).

On the free tier, GET /v1/management/usage/summary uses the same counting rules, so calls_remaining there equals limits.monthly_calls - usage_this_month for the current UTC month (up to the usage_log query cap).

{
  "account_id": "uuid",
  "tier": "builder",
  "subscription_status": "active",
  "current_period_end": "2026-04-24T00:00:00.000Z",
  "cancel_at_period_end": false,
  "canceled_at": null,
  "cancel_at": null,
  "trial_start": "2026-03-24T00:00:00.000Z",
  "trial_end": "2026-03-31T00:00:00.000Z",
  "billing_cycle_anchor": "2026-03-24T00:00:00.000Z",
  "limits": {
    "monthly_calls": 5000,
    "rate_limit_per_min": 100,
    "max_keys": 5
  },
  "usage_this_month": 1234
}

Notes:

• Lifecycle billing fields are nullable and become populated after relevant webhook events are processed.
• Timestamps are ISO-8601 UTC strings.

GET /v1/management/keys

Lists active standard keys only (never returns raw keys).

{
  "keys": [
    {
      "id": "key_uuid",
      "label": "production-worker-1",
      "prefix": "sk_live_••••2b4a",
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ],
  "count": 1,
  "max": 5
}

POST /v1/management/keys

Creates a standard key and returns it once.

Request:

{
  "label": "production-worker-1"
}

Response (201):

{
  "id": "key_uuid",
  "key": "sk_live_...",
  "label": "production-worker-1",
  "created_at": "2026-03-24T10:00:00.000Z",
  "warning": "Store this key securely. It will not be shown again."
}

DELETE /v1/management/keys/{id}

Revokes a standard key immediately.

Response: 204 No Content

404 example:

{
  "error": "key_not_found",
  "message": "No active key found with that ID for this account.",
  "action": "Check the key id and try again.",
  "docs": "https://docs.truval.dev/api/management#keys"
}

GET /v1/management/usage

Daily billable verifications for the last 30 days (includes zero-call days). Counts match Stripe meter usage: layer-1 syntax-only outcomes are excluded; disposable, no-MX, SMTP, and successful paths each count once per email. See Email verify — billing.

Note: This endpoint is billable for all tiers. On the free tier, the sum of daily calls may not equal GET /v1/management/usage/summary calls_used, because that summary uses monthly quota counting (aligned with verify enforcement). For preflight against verify limits on free, use GET /v1/management/usage/summary or GET /v1/management/account, not the daily series alone.

{
  "days": [
    { "date": "2026-03-24", "calls": 412 },
    { "date": "2026-03-23", "calls": 0 }
  ]
}

GET /v1/management/usage/summary

Month-to-date totals for the current UTC calendar month:

• Free tier: calls_used, calls_remaining, and overage_calls use the same monthly quota rules as the public verify API and as GET /v1/management/account usage_this_month (monthly quota).
• Builder and scale: the same fields use billable counting (same definition as GET /v1/management/usage and the Stripe meter).

Use this endpoint (or GET /v1/management/account) to compare remaining headroom to batch size before calling verify.

{
  "period": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.000Z"
  },
  "calls_used": 1234,
  "calls_included": 5000,
  "calls_remaining": 3766,
  "overage_calls": 0,
  "estimated_cost_eur": 9,
  "tier": "builder"
}

POST /v1/management/billing/portal

Creates a Stripe portal session URL.

Request:

{
  "return_url": "https://your-app.com/settings"
}

Response:

{
  "url": "https://billing.stripe.com/session/..."
}

Permission model

Endpoint family	sk_live_...	sk_mgmt_...
/v1/email/*	Yes	No
/v1/management/*	No	Yes

If a key type is wrong for an endpoint, API returns 403:

{
  "error": "wrong_key_type",
  "message": "Management endpoints require a provisioning key (sk_mgmt_...).",
  "action": "Create a provisioning key at https://dash.truval.dev",
  "docs": "https://docs.truval.dev/api/management#authentication"
}

All management (and shared auth) error codes, including supabase_error, key_limit_reached, and billing errors, are documented in Error reference.

Limits by tier

Tier	Rate limit (req/min)	Max standard keys	Included volume
Free	10	2	500 verification units / UTC calendar month
Builder	100	5	5,000 billable verifications / subscription period
Scale	1,000	10	100,000 billable verifications / subscription period

At most one active provisioning key (sk_mgmt_...) per account at any time. Attempting to create a second active provisioning key returns 409 (supabase_error); revoke the existing one first.

Public Repositories

• SDK: truval-dev/truval-sdk
• MCP Server: truval-dev/truval-mcp-server
• Agent Skills: truval-dev/truval-skills