---
title: "Request Free Key"
method: POST
path: "/free-keys"
tags: ["free keys"]
---

# Request Free Key

`POST /free-keys`

## Request

- Base URL: `https://api.licenscheck.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.licenscheck.com/free-keys`
- Auth: none declared

Issue a free key (50 searches a day, no verdicts) and email it; it replaces the inbox's earlier free key once it's used.

The key is stored only once the email has been accepted for delivery, so
an email that fails leaves no key behind and the old one still working.
A keyless visitor gets 3 signups per 10 minutes and 10 a day; any one
inbox gets 2 per 10 minutes and 3 a day, so nobody can flood someone
else's inbox or keep revoking their key. A filled-in hidden `website`
field is a bot: acknowledged the same way, but nothing is sent. Each
signup is posted to the key-requests Discord channel after responding.

Args:
    body: The signup.
    background: Runs the Discord post after responding.
    caller: Injected caller, for the per-visitor limit.
    repo: Injected `ApiKeyRepository`.

Returns:
    The acknowledgement.

Raises:
    HTTPException: 503 when no email service is configured; 422 for a
        throwaway inbox; 429 past either limit; 502 if the email didn't send.

## Request body

- FreeKeyIn: One filled-in free key signup.
  - `email` string, required: Where to send the key.
  - `name` string, nullable: Who's signing up, if they say.
  - `company` string, nullable: Their company, if any.
  - `website` string: Leave empty. A field hidden from people, which only bots fill in; a filled one is dropped.

## Response `202`

Successful Response

- FreeKeyOut: The acknowledgement the signup shows.
  - `sent` boolean, required: Always true: the key is on its way to the email given.

## Other responses

- `422`: The email isn't valid, or is at a throwaway-inbox service.
- `429`: Too many signups from this visitor or for this email; retry after Retry-After seconds.
- `502`: The email couldn't be sent; no key was issued.
- `503`: Free keys aren't open here (no email service configured).

---

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