vault/website/content/api-docs/system/rate-limit-quotas.mdx

---
layout: api
page_title: /sys/quotas/rate-limit - HTTP API
description: The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate limit quotas.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# `/sys/quotas/rate-limit`

@include 'alerts/restricted-admin.mdx'

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.

| Method | Path                           |
| :----- | :----------------------------- |
| `POST` | `/sys/quotas/rate-limit/:name` |

### 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: "")` – <EnterpriseAlert product="vault" inline /> 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)` – <EnterpriseAlert product="vault" inline /> 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

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

### Sample request

```shell-session
$ 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.

| Method   | Path                           |
| :------- | :----------------------------- |
| `DELETE` | `/sys/quotas/rate-limit/:name` |

### Sample request

```shell-session
$ 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.

| Method | Path                           |
| :----- | :----------------------------- |
| `GET`  | `/sys/quotas/rate-limit/:name` |

### Sample request

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

### Sample response

```json
{
  "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.

| Method | Path                     |
| :----- | :----------------------- |
| `LIST` | `/sys/quotas/rate-limit` |

### Sample request

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

### Sample response

```json
{
  "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
}
```