Skip to content
Products
/
/
/
API Key IP Allowlist
Last updated

API Key IP Allowlist

Using the Treasure Data API, our customers have additional IP Allowlist access control for API Keys. This lets you restrict API Key access to trusted IP ranges for stronger protection of your account and keys.

Restriction Scopes

The restriction_scope parameter defines how an IP Allowlist entry applies to traffic.

  • all: restricts both browser and API key access to the listed IPs. This is the IP Allowlist setting if IP Allowlist is configured through the web console. It can also be configured through API calls.

  • api_key_only: restricts only API key access; the user’s browser access is unaffected. This setting can only be configured through API calls.

This parameter can be configured at the account/network level to affect all users and/or at the individual user level. If both configurations exist, the user level configuration always replaces the account level account IP allowlist for a given user.

Priority Rules

  1. IP Access if both all & api_key_only are configured in IP Allowlist Entries
restriction_scope = all & restriction_scope = api_key_onlyIP matches both all & api_key_onlyIP matches only allIP matches only api_key_onlyNo IP matches
User's Browser Access✅✅✅¹❌
User's API Key Access✅❌²✅❌

Note :

  1. No default deny access rule exists for restriction_scope = all;

  2. Default deny access triggered if restriction_scope = api_key_only is configured

  1. IP Access if only all is configured in IP Allowlist Entries
restriction_scope = allIP matchesIP not matches
User's Browser Access✅❌
User's API Key Access✅❌
  1. IP Access if only api_key_only is configured in IP Allowlist Entries
restriction_scope = api_key_onlyIP matchesIP not matches
User's Browser Access✅✅
User's API Key Access✅❌
  1. User Access if IP Allowlist function is not configured
restriction_scope not configuredAll Account Users
User's Browser Access✅
User's API Key Access✅

Create Account or User level API Key IP Allowlist

Similar to IP Allowlist configurations in the console, using API calls, you can set up IP Allowlist for API key at the account level to cover all users, or at the individual user level. User-specific entries take precedence over account-level entries.

The API endpoint for IP Allowlist is /v4/ip_whitelist_entries Following is an example to create an API key IP Allowlist entry for a single user

POST /v4/ip_whitelist_entries
{
  "ip": "192.168.100.0/24",
  "user_id": "test_user_id",
  "restriction_scope": "api_key_only"
}

To apply API key IP Allowlist to all users of the customer account, Include account_id in the POST request:

POST /v4/ip_whitelist_entries

{
  "ip": "192.168.200.0/24",
  "account_id": "test_account_id",
  "restriction_scope": "api_key_only"
}

Read IP Allowlist Entries

To retrieve all IP Allowlist entries, send a GET request to /v4/ip_whitelist_entries. The response will include the restriction_scope for each entry.

GET /v4/ip_whitelist_entries

Update IP Allowlist Entry

To update an existing IP Allowlist entry, send a PATCH request to /v4/ip_whitelist_entries/{id} with the ID of the entry and the new restriction_scope value.

PATCH /v4/ip_whitelist_entries/{id}

{
  "restriction_scope": "all"
}

Delete IP Allowlist Entry

To delete an IP Allowlist entry, send a DELETE request to /v4/ip_whitelist_entries/{id} with the ID of the entry.

DELETE /v4/ip_whitelist_entries/{id}
Previous page
Next page