/sys/quotas/rate-limit

The /sys/quotas/rate-limit endpoint is used to create, edit and delete rate limit quotas.

Create or update a rate limit quota

This endpoint is used to create a rate limit quota with an identifier, name. A rate limit quota must include a rate value with an optional path that can either be a namespace or mount, and can optionally include a path suffix following the mount to restrict more specific API paths.

Parameters

• name (string: "") - The name of the quota.
• path (string: "") - Path of the mount or namespace to apply the quota. A blank path configures a global rate limit quota. For example namespace1/ adds a quota to a full namespace, namespace1/auth/userpass adds a quota to userpass in namespace1, and namespace1/kv-v2/data/foo/bar adds a quota to a specific secret on a KV v2 mount in namespace1. A trailing glob (*) can also be added as part of the path after the mount to match paths that share the same prefix prior to the glob. namespace1/kv-v2/data/foo/* would match both namespace1/kv-v2/data/foo/bar and namespace1/kv-v2/data/foo/baz. Updating this field on an existing quota can have "moving" effects. For example, updating namespace1 to namespace1/auth/userpass moves this quota from being a namespace quota to a namespace specific mount quota. Non-global quotas are not inherited by child namespaces. Quotas cannot be created or modified in parent or sibling namespaces. Note, namespaces are supported in Enterprise only.
• rate (float: 0.0) - The maximum number of requests in a given interval to be allowed by the quota rule. The rate must be positive.
• interval (string: "") - The duration to enforce rate limiting for (default "1s").
• block_interval (string: "") - If set, when a client reaches a rate limit threshold, the client will be prohibited from any further requests until after the 'block_interval' has elapsed.
• role (string: "") - If set on a quota where path is set to an auth mount with a concept of roles (such as /auth/approle/), this will make the quota restrict login requests to that mount that are made with the specified role. The request will fail if the auth mount does not have a concept of roles, or path is not an auth mount.
• inheritable (bool: false) - If set to true on a quota where path is set to a namespace, the same quota will be cumulatively applied to all child namespace. The inheritable parameter cannot be set to true if the path does not specify a namespace. Only quotas associated with the root namespace quotas are inheritable by default.
• group_by (string: "") – EnterpriseEnterprise Attribute by which to group requests by. Valid group_by modes are: 1) ip that groups requests by their source IP address (group_by defaults to ip if unset, which is the only supported mode in community edition); 2) none that groups together all requests that match the rate limit quota rule; 3) entity_then_ip that groups requests by their entity ID for authenticated requests that carry one, or by their IP for unauthenticated requests (or requests whose authentication is not connected to an entity); and 4) entity_then_none which also groups requests by their entity ID when available, but the rest is all grouped together (i.e. unauthenticated or with authentication not connected to an entity).
• secondary_rate (float: 0.0) – EnterpriseEnterprise Can only be set for the group_by modes entity_then_ip or entity_then_none. This is the rate limit applied to the requests that fall under the "ip" or "none" groupings, while the authenticated requests that contain an entity ID are subject to the rate field instead. Defaults to the same value as rate.

Sample payload

{
  "path": "",
  "rate": 897.3,
  "interval": "2m",
  "block_interval": "5m"
}

Sample request

$ curl \
    --request POST \
    --header "X-Vault-Token: ..." \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter

Delete a rate limit quota

A rate limit quota can be deleted by name. Quotas that exist in a parent or a sibling namespace cannot be deleted.

Sample request

$ curl \
    --request DELETE \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter

Get a rate limit quota

A rate limit quota can be retrieved by name. A quota can be read from any namespace. This behavior differs from modifying and deleting quotas which is not allowed within parent or sibling namespaces.

Sample request

$ curl \
    --request GET \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter

Sample response

{
  "request_id": "d0870811-455d-3dfd-459f-aee016e6fb68",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "block_interval": 300,
    "group_by": "ip",
    "interval": 2,
    "name": "global-rate-limiter",
    "path": "",
    "rate": 897.3,
    "role": "",
    "secondary_rate": 0,
    "type": "rate-limit"
  },
  "warnings": null
}

List rate limit quotas

This endpoint returns a list of all the rate limit quotas across all namespaces. Note that this level of access differs from creating, updating, and deleting quotas which restricts access to parent and sibling namespaces.

Sample request

$ curl \
    --request LIST \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/quotas/rate-limit

Sample response

{
  "auth": null,
  "data": {
    "keys": ["global-rate-limiter", "kv-rate-limiter"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false,
  "request_id": "ab633ee1-a692-ba03-083b-f1bd91c51c28",
  "warnings": null,
  "wrap_info": null
}