MaxMind provides a License Key Validation API, a tool for developers and
organizations seeking to verify the validity of MaxMind license keys within
their systems. This API endpoint is designed to check the existence and the
format of a license key. It does not provide information about the license key's
access to MaxMind products or the account to which it is associated. Using other
endpoints to check for the validity of a license key would fail as accounts have
access to particular services only.

You can use this API for building tools to scan your code for secrets to ensure
that secrets are not published in improper locations. One example of such a tool
is [trufflehog](https://github.com/trufflesecurity/trufflehog). Using such a
tool, you can prevent license keys accidentally ending up in unexpected places
and enhance the security of your applications.

You can use the
[License Key Validation OpenAPI specification](https://github.com/maxmind/openapi/blob/main/bundled/license-key-validation.yaml)
([raw file](https://raw.githubusercontent.com/maxmind/openapi/main/bundled/license-key-validation.yaml))
with API tools and code generators.

## Request

### Request URI

API calls should be made with an HTTP POST request to:

`https://secret-scanning.maxmind.com/secrets/validate-license-key`

### Authorization/Security

There is no authorization needed for this endpoint. The request is made using
the license key itself.

### Request Body

The Content Type of the request must be `application/x-www-form-urlencoded`. No
other content types are accepted at the moment.

The request body must include the following field:

| Key           | Value Type | Description                                                                     |
| ------------- | ---------- | ------------------------------------------------------------------------------- |
| `license_key` | string     | The `license_key` field must contain the license key that you want to validate. |

If the body has no `license_key` field, the server returns `400 Bad Request`
with the code `LICENSE_KEY_INVALID`.

Here is an example of how to make the request using curl:

```bash
curl https://secret-scanning.maxmind.com/secrets/validate-license-key \
    -d "license_key=your_license_key_here"
```

Please replace "your_license_key_here" with the actual license key you want to
validate.

## Response

HTTP status codes are used to relay success and error messages. A successful
POST will return a 204 (No Content) status code.

When the server returns an error (4xx or 5xx), the response may include a JSON
document in the body. This document is a single object with the keys `code` and
`error`. The `code` field is a static error code for machine use. The value of
any given code will never change, though codes can be added or removed. The
`error` field is a human-readable description of the error and may change at any
time.

### Response Body (for successful requests)

When the license key is successfully validated, the server will return a status
of `204 No Content`.

### Response Body (for unauthorized license keys)

When the license key is in the correct format but could not be validated in our
database, the server will return a JSON object with the following structure:

```json
{
  "code": "AUTHORIZATION_INVALID",
  "error": "Your account ID or license key could not be authenticated."
}
```

The HTTP status will be `401 Unauthorized`.

### Response Body (for unsuccessful requests)

In the event of an error occurring such as a bad request that has a license key
with a bad format, the server will return a JSON object with the following
structure:

```json
{
  "code": "LICENSE_KEY_INVALID",
  "error": "'foo-bad-license-key' is not a valid license_key when calling /secrets/validate-license-key."
}
```

The HTTP status will be a `400 Bad Request`.

### Response Body (for accounts without permission)

If the account that owns the license key does not have permission to use this
service, the server returns a JSON object with the following structure:

```json
{
  "code": "PERMISSION_REQUIRED",
  "error": "You do not have permission to use this service interface."
}
```

The HTTP status will be `403 Forbidden`. This response means that MaxMind
recognizes the license key. An unknown key gets a `401 Unauthorized` response
instead.

### Response Body (for large requests)

If the request body is larger than 65,536 bytes, the server returns a
`413 Content Too Large` status. The response does not have a JSON body.

### Response Body (for server errors)

If MaxMind cannot process the request, the server returns a JSON object with the
code `SERVER_ERROR` and a `500 Internal Server Error` status. You may also
receive a `503 Service Unavailable` status, which does not have a JSON body. In
both cases, you can try the request again later.