nomad/website/content/api-docs/operator/keyring.mdx

---
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 Active Public Keys

This endpoint retrieves a list of active public keys used to sign [workload
identities][wi]. The response is in the [JWKS][rfc7517] format as is commonly
used by JWT auth methods.

| Method | Path                        | Produces           |
|--------|-----------------------------|--------------------|
| `GET`  | `/.well-known/jwks.json`    | `application/json` |

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

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

### Sample Request

```shell-session
$ nomad operator api '/.well-known/jwks.json'
```

### Sample Response

```json
{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "15a95f48-001a-8be5-5da9-d94901d022c9",
      "alg": "RS256",
      "n": "6sImUQR6A...FB7bKn02dKw",
      "e": "AQAB"
    },
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "b7f6a3a7-14f9-4ac5-f713-32c9bce1fa93",
      "alg": "RS256",
      "n": "zEdiUB3DFuM...ii3kQvOf_eDApBDWJhfQw",
      "e": "AQAB"
    }
  ]
}
```

## OIDC Discovery

This endpoint retrieves [OIDC configuration metadata][oidc-disco] for using
[workload identities][wi] with third party services. Nomad will act as an
identity provider (IDP) to allow third parties to authenticate workload
identity JWTs based on the OIDC configurationa and JWKS.

Most third parties will require this endpoint be accessible through a
publically resolvable domain name and HTTPS signed by a trusted certificate
authority.

You must set the [`oidc_issuer`][oidc_issuer] Server agent configuration
parameter before this endpoint is enabled. In most situations you will also
need to run a proxy or load balancer for in front of this endpoint to serve the
contents with HTTPS using a trusted certificate.

| Method | Path                                | Produces           |
|--------|-------------------------------------|--------------------|
| `GET`  | `/.well-known/openid-configuration` | `application/json` |

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

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

### Sample Request

```shell-session
$ nomad operator api '/.well-known/openid-configuration'
```

### Sample Response

```json
{
  "id_token_signing_alg_values_supported": [
    "RS256",
    "EdDSA"
  ],
  "issuer": "http://example.com",
  "jwks_uri": "http://example.com/.well-known/jwks.json",
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public"
  ]
}
```

## 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` |

### Parameters

- `force` `(bool: false)` - Remove the key even if it was used to sign an existing variable
or workload identity.

### 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/manage/key-management
[`nomad operator root keyring`]: /nomad/commands/operator/root/keyring-rotate
[blocking queries]: /nomad/api-docs#blocking-queries
[oidc-disco]: https://openid.net/specs/openid-connect-discovery-1_0.html
[oidc_issuer]: /nomad/docs/configuration/server#oidc_issuer
[required ACLs]: /nomad/api-docs#acls
[rfc7517]: https://datatracker.ietf.org/doc/html/rfc7517
[wi]: /nomad/docs/concepts/workload-identity