Key Validation API
Validate locker keys and check their expiry status with our simple REST API.
Endpoint
GET /api/v1/keys/validate
POST /api/v1/keys/validate
POST /api/v1/keys/validate
Both GET and POST methods are supported. Use GET for simple queries and POST for applications that prefer request bodies.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | The key to validate (format: XXXX-XXXX-XXXX) |
Request Examples
GET Request
GET /api/v1/keys/validate?key=A7K9-2M3X-P8L4
Use this format when making GET requests. The key parameter is passed as a query string.
POST Request
POST /api/v1/keys/validate
Content-Type: application/json
{
"key": "A7K9-2M3X-P8L4"
}
Content-Type: application/json
{
"key": "A7K9-2M3X-P8L4"
}
Use this format when making POST requests. The key is passed in the request body as JSON.
Response Schema
Success Response
{
"valid": true,
"expiresAt": "2025-01-20T15:30:00.000Z",
"lockerId": "uuid-string",
"lockerTitle": "Premium Content Access"
}
"valid": true,
"expiresAt": "2025-01-20T15:30:00.000Z",
"lockerId": "uuid-string",
"lockerTitle": "Premium Content Access"
}
Response Fields
| Field | Type | Description |
|---|---|---|
| valid | boolean | Whether the key is valid and not expired |
| expiresAt | string (ISO 8601) | When the key expires (null if never expires) |
| lockerId | string | Unique identifier of the associated locker |
| lockerTitle | string | Title of the associated locker |
Invalid Response
{
"valid": false,
"reason": "expired" | "not_found" | "invalid_format"
}
"valid": false,
"reason": "expired" | "not_found" | "invalid_format"
}
Invalid Reasons
- expired - The key has expired
- not_found - The key doesn't exist in our database
- invalid_format - The key format is incorrect
Status Codes
200Success- Request completed successfully
400Bad Request- Missing or invalid key parameter
500Internal Server Error- Server error occurred
Important Notes
- • Public endpoint: No authentication required
- • Auto-cleanup: Expired keys are automatically deleted from the database
- • Key format: Keys follow the format XXXX-XXXX-XXXX (alphanumeric)
- • Validation: The API validates key format before checking the database
- • Rate limited: 100 requests per minute per IP address
Example Integration
JavaScript Example
async function validateKey(key) {
try {
const response = await fetch(
`/api/v1/keys/validate?key=${key}`
);
const data = await response.json();
return data.valid;
} catch (error) {
console.error('Validation failed:', error);
return false;
}
}
try {
const response = await fetch(
`/api/v1/keys/validate?key=${key}`
);
const data = await response.json();
return data.valid;
} catch (error) {
console.error('Validation failed:', error);
return false;
}
}