---
title: "Mint a complimentary-access grant code (platform admin only)"
method: POST
path: "/v1/admin/plan-grants"
tags: ["admin"]
---

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

`POST /v1/admin/plan-grants`

## Request

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

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.

## Request body

- object
  - `plan` 'free' | 'pro' | 'team' | 'selfhost', required: The tier this code grants on redemption.
  - `note` string: Shown to the redeeming org, e.g. "Courtesy of Postbag".
  - `expires_at` string, date-time: When the code itself stops being redeemable. Omit for a code that never expires on its own.
  - `max_redemptions` integer: How many different organizations may redeem this code.
  - `plan_duration_days` integer: How many days after redemption the granted plan lasts. Omit for a grant with no automatic expiry.

## Response `201`

created

- PlanGrantCreated
  - `id` string, required
  - `plan` 'free' | 'pro' | 'team' | 'selfhost', required
  - `note` string, nullable, required
  - `expires_at` string, nullable, required
  - `plan_duration_days` integer, nullable, required
  - `max_redemptions` integer, required
  - `redeemed_count` integer, required
  - `created_by_user_id` string, required
  - `created_at` string, required
  - `revoked_at` string, nullable, required
  - `code` string, required: Shown once — store it immediately. Only its hash is kept.

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Not found
- `409`: Error
- `422`: Error

---

[API](https://skmtc.dev/postbag/apis/postbag-api.md) · [All operations](https://skmtc.dev/postbag/apis/postbag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postbag/apis/postbag-api/revisions/3da976524695?raw)