Test API Key

Validates the API key and returns information about the key and associated organization.

Endpoint

GET /api/v1/test-key

Request

Headers

Header	Required	Description
Authorization	Yes*	Bearer <api-key>
X-API-Key	Yes*	Alternative to Authorization header

INFO

One of Authorization or X-API-Key is required.

Query Parameters

None.

Response

Success (200)

Returns API key validation status and usage information.

{
	"success": true,
	"message": "API key validation successful! -1 Request",
	"timestamp": "2025-12-10T14:30:00.000Z",
	"organization_id": "org_abc123",
	"api_key_info": {
		"uid": "key_xyz789",
		"name": "Production API Key",
		"current_usage": 1500,
		"max_api_requests": 10000,
		"created_at": "2025-01-15T09:00:00.000Z"
	}
}

Response Fields

Field	Type	Description
success	boolean	Whether validation was successful
message	string	Validation status message
timestamp	string	ISO timestamp of the validation
organization_id	string	Unique identifier for your organization
api_key_info	object	Detailed information about the API key

API Key Info Object

Field	Type	Description
uid	string	Unique identifier for the API key
name	string	User-defined name for the API key
current_usage	number	Number of API calls made in current billing period
max_api_requests	number	Maximum allowed API calls per billing period
created_at	string	ISO timestamp when the key was created

Error Responses

Status	Response	Description
401	{ "statusCode": 401, "statusMessage": "Valid API key required" }	No API key provided
403	{ "error": true, "statusCode": 403, "message": "Invalid API key" }	Invalid or expired API key

Examples

Using Bearer Token

curl -X GET "https://ipswamp.com/api/v1/test-key" \
  -H "Authorization: Bearer your-api-key-here"

Using X-API-Key Header

curl -X GET "https://ipswamp.com/api/v1/test-key" \
  -H "X-API-Key: your-api-key-here"

JavaScript/TypeScript

const response = await fetch("https://ipswamp.com/api/v1/test-key", {
	headers: {
		Authorization: "Bearer your-api-key-here",
	},
});

const data = await response.json();
console.log(
	`Usage: ${data.api_key_info.current_usage} / ${data.api_key_info.max_api_requests}`
);

Python

import requests

url = "https://ipswamp.com/api/v1/test-key"
headers = {
    "Authorization": "Bearer your-api-key-here"
}

response = requests.get(url, headers=headers)
data = response.json()

if data['success']:
    info = data['api_key_info']
    print(f"Usage: {info['current_usage']} / {info['max_api_requests']}")

Use Cases

1. Validate API Key on Application Startup

Test your API key when your application initializes to ensure proper configuration:

async function validateAPIKey() {
	try {
		const response = await fetch(
			"https://ipswamp.com/api/v1/test-key",
			{
				headers: { Authorization: `Bearer ${process.env.API_KEY}` },
			}
		);

		if (!response.ok) {
			throw new Error("Invalid API key");
		}

		console.log("✓ API key validated successfully");
	} catch (error) {
		console.error("✗ API key validation failed:", error);
		process.exit(1);
	}
}

2. Monitor Usage

Check remaining API quota before making expensive operations:

async function checkQuota() {
	const response = await fetch("https://ipswamp.com/api/v1/test-key", {
		headers: { Authorization: `Bearer ${apiKey}` },
	});

	const data = await response.json();
	const { current_usage, max_api_requests } = data.api_key_info;
	const remaining = max_api_requests - current_usage;

	if (remaining < 100) {
		console.warn(`Low quota: ${remaining} requests remaining`);
	}

	return remaining;
}

3. Display Usage in Dashboard

Show real-time usage statistics to users:

async function getUsageStats() {
	const response = await fetch("https://ipswamp.com/api/v1/test-key", {
		headers: { Authorization: `Bearer ${apiKey}` },
	});

	const data = await response.json();
	const { current_usage, max_api_requests, name } = data.api_key_info;

	return {
		keyName: name,
		used: current_usage,
		limit: max_api_requests,
		percentage: ((current_usage / max_api_requests) * 100).toFixed(1),
	};
}

Best Practices

1. Startup Validation: Test your API key when your application starts
2. Regular Monitoring: Periodically check usage to avoid hitting limits
3. Error Handling: Implement proper error handling for key validation failures
4. Alerting: Set up alerts when usage approaches the limit
5. Logging: Log validation attempts for debugging and security auditing

Rate Limiting

Important

The test-key endpoint does increment your usage counter, so avoid calling it unnecessarily.

Consider caching the validation result and checking usage only when needed, rather than on every request.

See Also

• Authentication - Authentication methods and security
• Check IP - Main IP checking endpoint
• Response Types - TypeScript interfaces for responses