---
title: "Provision a free-tier API key"
method: POST
path: "/v1/keys"
tags: ["Billing"]
---

# Provision a free-tier API key

`POST /v1/keys`

## Request

- Base URL: `https://api.hempdata.io`
- URL: `https://api.hempdata.io/v1/keys`
- Auth: none required

Mint a free-tier subscriber + key pair. No card required — this is the honest alias for the free branch of /v1/billing/checkout, which keeps working for existing callers. Paid tiers go through /v1/billing/checkout (Stripe Checkout needs redirect URLs).

## Request body

- FreeKeyRequest
  - `email` string, email, required
  - `tier` 'free'
  - `intended_tier` 'retailer' | 'brand' | 'enterprise': Optional: which paid tier you intend to upgrade to (conversion signal only)

## Response `201`

Free tier activated; keys shown once

- ApiResponseFreeKey
  - `success` boolean, required
  - `data` object, required
    - `subscriber_id` string, required
    - `tier` string, required
    - `api_key` string, required: Secret key (hda_live_sk_...) — shown once, store it now
    - `publishable_key` string, required: Publishable key (hda_live_pk_...) for the embeddable widget
    - `message` string
  - `meta` object, nullable
  - `errors` unknown

## Other responses

- `400`: Missing email, or a non-free tier was requested
- `409`: A subscriber with this email already exists
- `429`: Per-IP limit exceeded

---

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