ApiKeyIpRestriction
Controls network access for API keys by defining IP address whitelists and blacklists. This security layer ensures that even if an API key is compromised, it can only be used from pre-approved network locations. Organizations use this to restrict API access to their office networks, data centers, or specific cloud services. The entity supports both individual IP addresses and CIDR notation for entire network ranges, making it flexible enough for various network architectures. Restrictions can be set as 'allow' (whitelist) or 'deny' (blacklist), with the ability to combine both for complex access policies. For example, you might allow an entire corporate network range but deny specific compromised machines within it. This is particularly important for high-privilege API keys that can modify critical data. The system typically checks these restrictions on every API request, comparing the source IP against all active rules for that key. Cloud services often require this feature to ensure customer API keys can only be used from their documented IP ranges, preventing unauthorized access even if credentials leak.
Properties
| Property | Type | Mode | Description | Required |
|---|---|---|---|---|
| apiKeyId | uuid | stored | The API key these IP restrictions apply to | Required |
| ipAddress | string | stored | IP address or CIDR range (supports IPv4 and IPv6) Example: | Required |
| restrictionType | string | enum | Whether this IP is allowed or denied Values: | Required |
| description | string | stored | Explanation of why this restriction exists Example: | Optional |
| priority | integer | stored | Order of evaluation (higher priority rules are checked first) | Optional |
| isTemporary | boolean | stored | Whether this is a temporary restriction | Optional |
| expiresAt | DateTime | stored | When this restriction expires (for temporary rules) | Optional |
| addedAt | DateTime | stored | When this restriction was created | Required |
| addedBy | User | stored | User who added this restriction | Optional |
| lastMatchedAt | DateTime | stored | Last time this rule matched an incoming request | Optional |
| matchCount | integer | stored | Number of times this rule has been matched | Optional |
| isActive | boolean | stored | Whether this restriction is currently enforced | Optional |
Examples
Example 1
{
"@type": "ApiKeyIpRestriction",
"apiKeyId": "key_550e8400",
"ipAddress": "10.0.0.0/8",
"restrictionType": "allow",
"description": "Internal corporate network - all offices",
"priority": 100,
"isTemporary": false,
"addedAt": "2024-01-15T10:00:00Z",
"addedBy": "admin_123",
"lastMatchedAt": "2024-03-15T14:30:00Z",
"matchCount": 5823,
"isActive": true
}Example 2
{
"@type": "ApiKeyIpRestriction",
"apiKeyId": "key_prod_789",
"ipAddress": "203.0.113.45",
"restrictionType": "deny",
"description": "Blocked due to suspicious activity detected from this IP",
"priority": 200,
"isTemporary": true,
"expiresAt": "2024-03-20T00:00:00Z",
"addedAt": "2024-03-15T16:00:00Z",
"addedBy": "security_bot",
"lastMatchedAt": "2024-03-15T16:30:00Z",
"matchCount": 47,
"isActive": true
}