admin

Mint a complimentary-access grant code (platform admin only)

Platform-admin only: allowed when the caller's email (the session user's email, or — for an API key — the owner member's email of the key's organization) is in the server's PLATFORM_ADMIN_EMAILS env var (comma-separated, empty by default). Any other caller gets 404 not_found, not 403, so a self-hosted operator who never sets PLATFORM_ADMIN_EMAILS never sees this endpoint exist. Touches no tenant — the code is redeemed by an org's own owner with POST /v1/plan/redeem, which is where plan_source actually changes.

post/v1/admin/plan-grants

Request

  • Base URL: https://postbag.dev
  • URL: https://postbag.dev/v1/admin/plan-grants
  • Auth: HTTP bearer

Request body

plan'free' | 'pro' | 'team' | 'selfhost' required

The tier this code grants on redemption.

notestring

Shown to the redeeming org, e.g. "Courtesy of Postbag".

expires_atstring date-time

When the code itself stops being redeemable. Omit for a code that never expires on its own.

max_redemptionsinteger

How many different organizations may redeem this code.

plan_duration_daysinteger

How many days after redemption the granted plan lasts. Omit for a grant with no automatic expiry.

Response

created

idstring required
plan'free' | 'pro' | 'team' | 'selfhost' required
notestring nullable required
expires_atstring nullable required
plan_duration_daysinteger nullable required
max_redemptionsinteger required
redeemed_countinteger required
created_by_user_idstring required
created_atstring required
revoked_atstring nullable required
codestring required

Shown once — store it immediately. Only its hash is kept.

Example response

{
  "id": "fm_8f3kq2",
  "expires_at": "2026-08-21T09:00:00.000Z",
  "created_at": "2026-08-21T09:00:00.000Z",
  "revoked_at": "2026-08-21T09:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.