Authentication

All API endpoints require an API key for authentication.

Authentication Methods

IPSwamp API supports two methods for providing your API key:

Bearer Token (Recommended)

Use the Authorization header with a Bearer token:

Authorization: Bearer <your-api-key>

Example:

curl -X GET "https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8" \
  -H "Authorization: Bearer your-api-key-here"

API Key Header

Alternatively, use the X-API-Key header:

X-API-Key: <your-api-key>

Example:

curl -X GET "https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8" \
  -H "X-API-Key: your-api-key-here"

Getting Your API Key

1. Log in to your IPSwamp dashboard
2. Navigate to API Settings
3. Generate a new API key or copy an existing one
4. Store your API key securely (never commit it to version control)

Security Warning

Keep your API keys secure. Never expose them in client-side code or public repositories.

Authentication Errors

Status Code	Description	Solution
401	API key not provided	Include API key in request headers
403	Invalid API key	Verify your API key is correct and active
403	Expired API key	Generate a new API key in the dashboard
403	Usage limit exceeded	Upgrade your plan or wait for usage reset

Error Response Format

{
	"error": true,
	"statusCode": 401,
	"message": "API key required..."
}

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.

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']}")

Best Practices

1. Use environment variables to store API keys
2. Rotate keys regularly for enhanced security
3. Create separate keys for development and production
4. Monitor usage via the test-key endpoint
5. Implement retry logic with exponential backoff for rate limits
6. Startup Validation: Test your API key when your application starts
7. Regular Monitoring: Periodically check usage to avoid hitting limits
8. Error Handling: Implement proper error handling for key validation failures
9. Alerting: Set up alerts when usage approaches the limit
10. Logging: Log validation attempts for debugging and security auditing

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.

Quota Tracking

Your API key tracks usage across all authenticated endpoints. Quota consumption varies by endpoint:

Endpoint	Quota Impact
/checkIP	1 per request
/checkIP/bulk	1 per IP found in database
/checkSubnet	1 per IP found in database
/export	1 per IP in export
/account	Does not count toward quota

Use the /account endpoint to inspect current API key usage and remaining quota.