---
title: "Upgrade a test key to a live free-grant key (6,000s credit)"
method: POST
path: "/v1/keys/upgrade"
tags: ["provisioning"]
---

# Upgrade a test key to a live free-grant key (6,000s credit)

`POST /v1/keys/upgrade`

## Request

- Base URL: `https://api.primateintelligence.ai`
- URL: `https://api.primateintelligence.ai/v1/keys/upgrade`
- Auth: HTTP bearer

Stage 1 of the key lifecycle. Call with a `pv_test_` key in Authorization; receive a `pv_live_` key with `tier: free_grant` and a 6,000-second credit grant. No email or card required. **GitHub-gated (PRI-479):** calling without a `github_token` returns `403 github_verification_required` whose `details` carry the OAuth `client_id` and device-flow URLs — complete GitHub's device flow and retry with `{"github_token": "..."}`. One free grant per GitHub account, ever (duplicate → `409 github_account_already_used`). IP caps (3 / IP / 24h) remain as secondary defense.

## Request body

- UpgradeKeyRequest
  - `github_token` string: PRI-479: GitHub OAuth access token from the device flow. Required when the GitHub gate is enabled (calling without one returns 403 github_verification_required with device-flow bootstrap details). Verified against GitHub and discarded — never stored. One free grant per GitHub account, ever.

## Response `201`

Live key issued. The raw `api_key` appears only in this response.

- UpgradeKeyResponse
  - `object` 'api_key', required
  - `livemode` true, required
  - `api_key` string, required: The raw `pv_live_` key — store securely, shown only once.
  - `tier` 'free_grant', required
  - `expires_at` string, date-time, required
  - `grant_seconds` integer, required
  - `note` string
  - `claim_flow` object
    - `endpoint` string, required
    - `how` string, required

## Other responses

- `401`: github_token_invalid — the supplied github_token failed verification with GitHub.
- `403`: test_mode_only — must call with a pv_test_ key. github_verification_required — GitHub gate enabled and no github_token supplied; `details` carry the device-flow bootstrap (client_id, URLs).
- `409`: github_account_already_used — this GitHub account has already claimed its free grant.
- `429`: upgrade_limit_exceeded — per-IP or global daily cap reached.

---

[API](https://skmtc.dev/primateintelligence/apis/primate-vision-api.md) · [All operations](https://skmtc.dev/primateintelligence/apis/primate-vision-api/llms.txt) · [OpenAPI document](https://skmtc.dev/primateintelligence/apis/primate-vision-api/revisions/aa51b01dc8ad?raw)