Create key

Start a free 14-day trial, or replace the key on an address you already have one on. The key arrives by email; it is never in the response body. No authentication is needed to start a trial.

curl -X POST "https://govconapi.com/api/v1/keys?email=YOUR_EMAIL"

{
  "status": "trial_created",
  "email": "[email protected]",
  "plan": "free",
  "trial_days_remaining": 14
}

The key is in your inbox. Confirm it with /api/v1/me.

Replacing a key you already have

Replacing a key deactivates every other key on that address, so this endpoint asks you to prove the address is yours. Either proof works, and which one you use depends on whether you still hold the key.

If you still have a working key, send it and the replacement is immediate:

curl -X POST "https://govconapi.com/api/v1/keys?email=YOUR_EMAIL" \
  -H "Authorization: Bearer YOUR_CURRENT_KEY"

If you have lost it, call the endpoint with no key. A 6-digit code goes to the address, and your current key keeps working until you send the code back:

curl -X POST "https://govconapi.com/api/v1/keys?email=YOUR_EMAIL"
# -> {"status": "code_sent", ...}

curl -X POST "https://govconapi.com/api/v1/keys?email=YOUR_EMAIL&code=123456"
# -> {"status": "key_regenerated", ...}

The code expires in 10 minutes, is good for one use, and is accepted five times before it is discarded. A key presented for a different address is treated as no key at all, and the code path applies.

Parameters

Accepted as query parameters or in a JSON body.

• email - the address the key belongs to (required)
• code - the 6-digit code from the email, when replacing a key you no longer hold
• plan - free on a first key. Replacements keep the plan the address already has; to change plans, use /api/v1/checkout

Response

• status - trial_created on a first key, code_sent when a code has been emailed, key_regenerated when the replacement is done
• email - the canonical form of the address, lowercased with any +tag removed, so [email protected] and [email protected] are one account and one trial
• plan - the plan the key carries
• message - a one-line description of what happened
• trial_days_remaining - 14, on trial_created only

Errors

• 400: email missing, or not a valid address.
• 401: the code is wrong or has expired. Call again with no code for a new one.
• 402: the trial on this address has ended, or the subscription is cancelled. Both bodies carry the pricing URL.
• 429: too many replacement requests. Five codes per address per 15 minutes, and five requests per minute from one caller.
• 502: the code email could not be sent. Nothing changed; try again in a minute.