---
layout: api
page_title: Keyring - Operator - HTTP API
description: |-
  The /operator/keyring endpoints provide tools for Nomad operators to interact with the root keyring.
---

# Keyring Operator HTTP API

The `/operator/keyring` endpoints manage encryption root keys used for storing
variables and signing workload identities, including examining active encryption
keys, rotating keys, or removing unused keys.

See the [Key Management] documentation for information how these capabilities
are used. For instructions on how to use the CLI to perform these operations
manually, please see the documentation for the [`nomad operator root keyring`]
commands.

## List Keys

This endpoint retrieves a list of root keys known to the cluster. Note that only
key metadata is returned and the key material is never made available via the
HTTP API.

| Method | Path                        | Produces           |
|--------|-----------------------------|--------------------|
| `GET`  | `/v1/operator/keyring/keys` | `application/json` |

The table below shows this endpoint's support for [blocking queries] and
[required ACLs].

| Blocking Queries | ACL Required |
|------------------|--------------|
| `YES`            | `management` |

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/operator/keyring/keys
```

### Sample Response

```json
[
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 13,
    "CreateTime": 1662665630638648800,
    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
    "ModifyIndex": 13,
    "State": "active"
  },
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 6,
    "CreateTime": 1662665528857979100,
    "KeyID": "64b96f4b-f167-f2dd-9148-7867f7e420e3",
    "ModifyIndex": 12,
    "State": "inactive"
  },
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 12,
    "CreateTime": 1662665624108063000,
    "KeyID": "f9725e52-9b49-5b55-a8eb-083e23db4a3e",
    "ModifyIndex": 13,
    "State": "inactive"
  }
]
```

## Rotate Key

This endpoint forces the server to rotate the active root key.

| Method | Path                          | Produces           |
|--------|-------------------------------|--------------------|
| `PUT`  | `/v1/operator/keyring/rotate` | `application/json` |

The table below shows this endpoint's support for [blocking queries] and
[required ACLs].

| Blocking Queries | ACL Required |
|------------------|--------------|
| `NO`             | `management` |


### Parameters

- `full` `(bool: false)` - Decrypt all existing variables and re-encrypt with
  the new key. This API request will immediately return and the re-encryption
  process will run asynchronously on the leader.


### Sample Request

```shell-session
$ curl \
    -XPUT \
    https://localhost:4646/v1/operator/keyring/rotate
```

### Sample Response

```json
{
  "Index": 13,
  "Key": {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 0,
    "CreateTime": 1662665630638648800,
    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
    "ModifyIndex": 0,
    "State": "active"
  }
}
```

## Delete Key

This endpoint deletes a root key in the `inactive` state.

| Method   | Path                               | Produces           |
|----------|------------------------------------|--------------------|
| `DELETE` | `/v1/operator/keyring/key/:key_id` | `application/json` |

The table below shows this endpoint's support for [blocking queries] and
[required ACLs].

| Blocking Queries | ACL Required |
|------------------|--------------|
| `NO`             | `management` |

### Sample Request

```shell-session
$ curl \
    -XDELETE \
    https://localhost:4646/v1/operator/keyring/key/68237d9-1770-4d34-9c41-1f220107fc10
```


### Sample Response

```json
{
  "Index": 16
}
```


[Key Management]: /nomad/docs/operations/key-management
[`nomad operator root keyring`]: /nomad/docs/commands/operator/root/keyring-rotate
[blocking queries]: /nomad/api-docs#blocking-queries
[required ACLs]: /nomad/api-docs#acls