2017-09-21 14:18:35 +00:00
---
layout: "api"
page_title: "Nomad Secret Backend - HTTP API"
New Docs Website (#5535)
* conversion stage 1
* correct image paths
* add sidebar title to frontmatter
* docs/concepts and docs/internals
* configuration docs and multi-level nav corrections
* commands docs, index file corrections, small item nav correction
* secrets converted
* auth
* add enterprise and agent docs
* add extra dividers
* secret section, wip
* correct sidebar nav title in front matter for apu section, start working on api items
* auth and backend, a couple directory structure fixes
* remove old docs
* intro side nav converted
* reset sidebar styles, add hashi-global-styles
* basic styling for nav sidebar
* folder collapse functionality
* patch up border length on last list item
* wip restructure for content component
* taking middleman hacking to the extreme, but its working
* small css fix
* add new mega nav
* fix a small mistake from the rebase
* fix a content resolution issue with middleman
* title a couple missing docs pages
* update deps, remove temporary markup
* community page
* footer to layout, community page css adjustments
* wip downloads page
* deps updated, downloads page ready
* fix community page
* homepage progress
* add components, adjust spacing
* docs and api landing pages
* a bunch of fixes, add docs and api landing pages
* update deps, add deploy scripts
* add readme note
* update deploy command
* overview page, index title
* Update doc fields
Note this still requires the link fields to be populated -- this is solely related to copy on the description fields
* Update api_basic_categories.yml
Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.
* Add bottom hero, adjust CSS, responsive friendly
* Add mega nav title
* homepage adjustments, asset boosts
* small fixes
* docs page styling fixes
* meganav title
* some category link corrections
* Update API categories page
updated to reflect the second level headings for api categories
* Update docs_detailed_categories.yml
Updated to represent the existing docs structure
* Update docs_detailed_categories.yml
* docs page data fix, extra operator page remove
* api data fix
* fix makefile
* update deps, add product subnav to docs and api landing pages
* Rearrange non-hands-on guides to _docs_
Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.
* WIP Redirects for guides to docs
* content and component updates
* font weight hotfix, redirects
* fix guides and intro sidenavs
* fix some redirects
* small style tweaks
* Redirects to learn and internally to docs
* Remove redirect to `/vault`
* Remove `.html` from destination on redirects
* fix incorrect index redirect
* final touchups
* address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
sidebar_title: "Nomad"
sidebar_current: "api-http-secret-nomad"
2017-09-21 14:18:35 +00:00
description: |-
This is the API documentation for the Vault Nomad secret backend.
---
# Nomad Secret Backend HTTP API
This is the API documentation for the Vault Nomad secret backend. For general
information about the usage and operation of the Nomad backend, please see the
[Vault Nomad backend documentation ](/docs/secrets/nomad/index.html ).
This documentation assumes the Nomad backend is mounted at the `/nomad` path
in Vault. Since it is possible to mount secret backends at any location, please
update your API calls accordingly.
## Configure Access
This endpoint configures the access information for Nomad. This access
information is used so that Vault can communicate with Nomad and generate
Nomad tokens.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/nomad/config/access` | `204 (empty body)` |
### Parameters
2017-12-17 14:10:56 +00:00
- `address` `(string: "")` – Specifies the address of the Nomad
2017-09-21 14:18:35 +00:00
instance, provided as `"protocol://host:port"` like `"http://127.0.0.1:4646"` .
2017-12-17 14:10:56 +00:00
This value can also be provided on individual calls with the NOMAD_ADDR
environment variable.
2017-09-21 14:18:35 +00:00
2017-12-17 14:10:56 +00:00
- `token` `(string: "")` – Specifies the Nomad Management token to use.
This value can also be provided on individual calls with the NOMAD_TOKEN
environment variable.
2017-09-21 14:18:35 +00:00
2018-08-16 19:48:23 +00:00
- `max_token_name_length` `(int: <optional>)` – Specifies the maximum length to
use for the name of the Nomad token generated with [Generate
Credential](#generate-credential). If omitted, `0` is used and ignored,
defaulting to the max value allowed by the Nomad version. For Nomad versions
0.8.3 and earlier, the default is `64` . For Nomad version 0.8.4 and later, the default is
`256` .
2017-09-21 14:18:35 +00:00
### Sample Payload
```json
{
"address": "http://127.0.0.1:4646",
2018-08-16 19:48:23 +00:00
"token": "adha...",
"max_token_name_length": 256
2017-09-21 14:18:35 +00:00
}
```
### Sample Request
```
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload .json \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/config/access
2017-09-21 14:18:35 +00:00
```
2017-11-29 16:53:42 +00:00
## Read Access Configuration
This endpoint queries for information about the Nomad connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/nomad/config/access` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/config/access
2017-11-29 16:53:42 +00:00
```
### Sample Response
```json
2017-12-17 14:10:56 +00:00
"data": {
"address": "http://localhost:4646/"
}
2017-11-29 16:53:42 +00:00
```
2017-11-06 15:13:50 +00:00
## Configure Lease
This endpoint configures the lease settings for generated tokens.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
2017-11-29 16:53:42 +00:00
| `POST` | `/nomad/config/lease` | `204 (empty body)` |
2017-11-06 15:13:50 +00:00
### Parameters
2017-12-15 22:06:56 +00:00
- `ttl` `(string: "")` – Specifies the ttl for the lease. This is provided
as a string duration with a time suffix like `"30s"` or `"1h"` or as total
seconds.
2017-11-06 15:13:50 +00:00
2017-12-15 22:06:56 +00:00
- `max_ttl` `(string: "")` – Specifies the max ttl for the lease. This is
provided as a string duration with a time suffix like `"30s"` or `"1h"` or as
total seconds.
2017-11-06 15:13:50 +00:00
### Sample Payload
```json
{
"ttl": 1800,
"max_ttl": 3600
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/config/lease
2017-11-06 15:13:50 +00:00
```
2017-11-29 16:53:42 +00:00
## Read Lease Configuration
This endpoint queries for information about the Lease TTL for the specified mount.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/nomad/config/lease` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/config/lease
2017-11-29 16:53:42 +00:00
```
### Sample Response
```json
2017-12-17 14:10:56 +00:00
"data": {
"max_ttl": 86400,
"ttl": 86400
}
2017-11-29 16:53:42 +00:00
```
2017-12-15 22:06:56 +00:00
## Delete Lease Configuration
This endpoint deletes the lease configuration.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/nomad/config/lease` | `204 (empty body)` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/config/lease
2017-12-15 22:06:56 +00:00
```
2017-09-21 14:18:35 +00:00
## Create/Update Role
This endpoint creates or updates the Nomad role definition in Vault. If the role does not exist, it will be created. If the role already exists, it will receive
updated attributes.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
2017-10-31 20:56:56 +00:00
| `POST` | `/nomad/role/:name` | `204 (empty body)` |
2017-09-21 14:18:35 +00:00
### Parameters
- `name` `(string: <required>)` – Specifies the name of an existing role against
which to create this Nomad tokens. This is part of the request URL.
2017-11-29 16:31:17 +00:00
- `policies` `(string: "")` – Comma separated list of Nomad policies the token is going to be created against. These need to be created beforehand in Nomad.
2017-09-29 10:23:47 +00:00
2017-11-29 16:31:17 +00:00
- `global` `(bool: "false")` – Specifies if the token should be global, as defined in the [Nomad Documentation ](https://www.nomadproject.io/guides/acl.html#acl-tokens ).
2017-09-29 10:23:47 +00:00
ma
2017-09-21 14:18:35 +00:00
2017-11-06 21:34:20 +00:00
- `type` `(string: "client")` - Specifies the type of token to create when
2017-09-21 14:18:35 +00:00
using this role. Valid values are `"client"` or `"management"` .
### Sample Payload
To create a client token with a custom policy:
```json
{
2017-11-29 16:31:17 +00:00
"policies": "readonly"
2017-09-21 14:18:35 +00:00
}
```
### Sample Request
```
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload .json \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/role/monitoring
2017-09-21 14:18:35 +00:00
```
## Read Role
This endpoint queries for information about a Nomad role with the given name.
If no role exists with that name, a 404 is returned.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
2017-10-31 20:56:56 +00:00
| `GET` | `/nomad/role/:name` | `200 application/json` |
2017-09-21 14:18:35 +00:00
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to query. This
is part of the request URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/role/monitoring
2017-09-21 14:18:35 +00:00
```
### Sample Response
```json
{
2017-12-17 14:10:56 +00:00
"data": {
"lease": "0s",
"policies": [
"example"
],
"token_type": "client"
}
2017-09-21 14:18:35 +00:00
}
```
## List Roles
This endpoint lists all existing roles in the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
2017-10-31 20:56:56 +00:00
| `LIST` | `/nomad/role` | `200 application/json` |
| `GET` | `/nomad/role?list=true` | `200 application/json` |
2017-09-21 14:18:35 +00:00
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/role
2017-09-21 14:18:35 +00:00
```
### Sample Response
```json
{
2017-12-17 14:10:56 +00:00
"data": {
"keys": [
"example"
]
}
2017-09-21 14:18:35 +00:00
}
```
## Delete Role
This endpoint deletes a Nomad role with the given name. Even if the role does
not exist, this endpoint will still return a successful response.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
2017-10-31 20:56:56 +00:00
| `DELETE` | `/nomad/role/:name` | `204 (empty body)` |
2017-09-21 14:18:35 +00:00
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample Request
```
$ curl \
--request DELETE \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/role/example-role
2017-09-21 14:18:35 +00:00
```
## Generate Credential
This endpoint generates a dynamic Nomad token based on the given role
definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/nomad/creds/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of an existing role against
which to create this Nomad token. This is part of the request URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/nomad/creds/example
2017-09-21 14:18:35 +00:00
```
### Sample Response
```json
{
2017-12-17 14:10:56 +00:00
"data": {
"accessor_id": "c834ba40-8d84-b0c1-c084-3a31d3383c03",
"secret_id": "65af6f07-7f57-bb24-cdae-a27f86a894ce"
}
2017-09-21 14:18:35 +00:00
}
```