upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-12-18 15:56:29 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 12

[DOCS] Retire legacy content files - CE (#9115)

Browse source 
* Retire legacy content files

* add repo link to main README
This commit is contained in:
Sarah Chavis 2025-09-08 14:23:06 -07:00 committed by GitHub
parent bbb6f1ea24
commit 0a39621e5f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1796 changed files with 17 additions and 185003 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
README.md
View file

@ -12,6 +12,7 @@
- Documentation: [https://developer.hashicorp.com/vault/docs](https://developer.hashicorp.com/vault/docs)
- Tutorials: [https://developer.hashicorp.com/vault/tutorials](https://developer.hashicorp.com/vault/tutorials)
- Certification exam: [https://developer.hashicorp.com/certifications/security-automation](https://developer.hashicorp.com/certifications/security-automation)
- Documentation source: [https://github.com/hashicorp/web-unified-docs](https://github.com/hashicorp/web-unified-docs)
<img width="300" alt="Vault Logo" src="https://github.com/hashicorp/vault/blob/f22d202cde2018f9455dec755118a9b84586e082/Vault_PrimaryLogo_Black.png">

18
website/.editorconfig
View file

@ -1,18 +0,0 @@
# This file is for unifying the coding style for different editors and IDEs
# editorconfig.org
root = true
[*]
end_of_line = lf
charset = utf-8
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2
[Makefile]
indent_style = tab
[{*.md,*.json}]
max_line_length = null

3
website/.env
View file

@ -1,3 +0,0 @@
NEXT_PUBLIC_ALGOLIA_APP_ID=YY0FFNI7MF
NEXT_PUBLIC_ALGOLIA_INDEX=product_VAULT
NEXT_PUBLIC_ALGOLIA_SEARCH_ONLY_API_KEY=9c555e8fa951c1c53e726c0ce2eb3b73

1
website/.env.production
View file

@ -1 +0,0 @@
HASHI_ENV=production

10
website/.eslintrc.js
View file

@ -1,10 +0,0 @@
/**
* Copyright (c) HashiCorp, Inc.
* SPDX-License-Identifier: BUSL-1.1
*/
module.exports = {
...require('@hashicorp/platform-cli/config/.eslintrc'),
/* Specify overrides here */
ignorePatterns: ['public/']
}

11
website/.gitignore vendored
View file

@ -1,11 +0,0 @@
node_modules
.DS_Store
.next
out
.mdx-data
# As per Next.js conventions (https://nextjs.org/docs/basic-features/environment-variables#default-environment-variables)
.env*.local
!.env*
website-preview

1
website/.nvmrc
View file

@ -1 +0,0 @@
v18

9
website/.stylelintrc.js
View file

@ -1,9 +0,0 @@
/**
* Copyright (c) HashiCorp, Inc.
* SPDX-License-Identifier: BUSL-1.1
*/
module.exports = {
...require('@hashicorp/platform-cli/config/stylelint.config'),
/* Specify overrides here */
}

11
website/Dockerfile
View file

@ -1,11 +0,0 @@
# Copyright (c) HashiCorp, Inc.
# SPDX-License-Identifier: BUSL-1.1
FROM docker.mirror.hashicorp.services/node:18.18.2-alpine
RUN apk add --update --no-cache git make g++ automake autoconf libtool nasm libpng-dev
COPY ./package.json /website/package.json
COPY ./package-lock.json /website/package-lock.json
WORKDIR /website
RUN npm install -g npm@latest
RUN npm install

58
website/Makefile
View file

@ -1,58 +0,0 @@
######################################################
# NOTE: This file is managed by the Digital Team's #
# Terraform configuration @ hashicorp/mktg-terraform #
######################################################
.DEFAULT_GOAL := website
# Set the preview mode for the website shell to "developer" or "io"
PREVIEW_MODE ?= developer
REPO ?= vault
# Enable setting alternate docker tool, e.g. 'make DOCKER_CMD=podman'
DOCKER_CMD ?= docker
CURRENT_GIT_BRANCH=$$(git rev-parse --abbrev-ref HEAD)
LOCAL_CONTENT_DIR=
PWD=$$(pwd)
DOCKER_IMAGE="hashicorp/dev-portal"
DOCKER_IMAGE_LOCAL="dev-portal-local"
DOCKER_RUN_FLAGS=-it \
--publish "3000:3000" \
--rm \
--tty \
--volume "$(PWD)/content:/app/content" \
--volume "$(PWD)/public:/app/public" \
--volume "$(PWD)/data:/app/data" \
--volume "$(PWD)/redirects.js:/app/redirects.js" \
--volume "next-dir:/app/website-preview/.next" \
--volume "$(PWD)/.env:/app/.env" \
-e "REPO=$(REPO)" \
-e "PREVIEW_FROM_REPO=$(REPO)" \
-e "IS_CONTENT_PREVIEW=true" \
-e "LOCAL_CONTENT_DIR=$(LOCAL_CONTENT_DIR)" \
-e "CURRENT_GIT_BRANCH=$(CURRENT_GIT_BRANCH)" \
-e "PREVIEW_MODE=$(PREVIEW_MODE)"
# Default: run this if working on the website locally to run in watch mode.
.PHONY: website
website:
@echo "==> Downloading latest Docker image..."
@$(DOCKER_CMD) pull $(DOCKER_IMAGE)
@echo "==> Starting website..."
@$(DOCKER_CMD) run $(DOCKER_RUN_FLAGS) $(DOCKER_IMAGE)
# Use this if you have run `website/build-local` to use the locally built image.
.PHONY: website/local
website/local:
@echo "==> Starting website from local image..."
@$(DOCKER_CMD) run $(DOCKER_RUN_FLAGS) $(DOCKER_IMAGE_LOCAL)
# Run this to generate a new local Docker image.
.PHONY: website/build-local
website/build-local:
@echo "==> Building local Docker image"
@$(DOCKER_CMD) build https://github.com/hashicorp/dev-portal.git\#main \
-t $(DOCKER_IMAGE_LOCAL)

547
website/README.md
View file

@ -1,538 +1,23 @@
# Vault Website
# Vault product documentation website
> [!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.
>
> **Vault documentation change**
>
> Vault product documentation no longer publishes from the `/website` directory.
This subdirectory contains the content for the [Vault Website](https://vaultproject.io/).
The Vault docs now live in the
[`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs)
repo under `/content/vault/`.
<!--
This readme file contains several blocks of generated text, to make it easier to share common information
across documentation website readmes. To generate these blocks from their source, run `npm run generate:readme`
You can still contribute to Vault docs by created a PR under
`hashicorp/web-unified-docs`:
Any edits to the readme are welcome outside the clearly noted boundaries of the blocks. Alternately, a
block itself can be safely "forked" from the central implementation simply by removing the "BEGIN" and
"END" comments from around it.
-->
- For content changes related to the monthly Vault update, submit PRs against
the monthly update branch (e.g., `vault/202509`).
## Table of Contents
- For content changes related to an upcoming Vault release, submit PRs against
the RC release branch (e.g., `vault/1.21.x`).
- [Contributions](#contributions-welcome)
- [Running the Site Locally](#running-the-site-locally)
- [Editing Markdown Content](#editing-markdown-content)
- [Editing Navigation Sidebars](#editing-navigation-sidebars)
- [Changing the Release Version](#changing-the-release-version)
- [Redirects](#redirects)
- [Browser Support](#browser-support)
- [Deployment](#deployment)
<!-- BEGIN: contributions -->
<!-- Generated text, do not edit directly -->
## Contributions Welcome!
If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀
<!-- END: contributions -->
<!-- BEGIN: local-development -->
<!-- Generated text, do not edit directly -->
## Running the Site Locally
The website can be run locally through node.js or [Docker](https://www.docker.com/get-started). If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node.
> **Note:** If you are using a text editor that uses a "safe write" save style such as **vim** or **goland**, this can cause issues with the live reload in development. If you turn off safe write, this should solve the problem. In vim, this can be done by running `:set backupcopy=yes`. In goland, search the settings for "safe write" and turn that setting off.
### With Docker
Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`.
The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run `make build-image` to generate a local Docker image with updated dependencies, then `make website-local` to use that image and preview.
### With Node
If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run:
- `npm install`
- `npm start`
...and then visit `http://localhost:3000`.
If you pull down new code from github, you should run `npm install` again. Otherwise, there's no need to re-run `npm install` each time the site is run, you can just run `npm start` to get it going.
<!-- END: local-development -->
<!-- BEGIN: editing-markdown -->
<!-- Generated text, do not edit directly -->
## Editing Markdown Content
Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/content` directory.
To create a new page with Markdown, create a file ending in `.mdx` in a `content/<subdirectory>`. The path in the content directory will be the URL route. For example, `content/docs/hello.mdx` will be served from the `/docs/hello` URL.
> **Important**: Files and directories will only be rendered and published to the website if they are [included in sidebar data](#editing-navigation-sidebars). Any file not included in sidebar data will not be rendered or published.
This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys.
```yaml
---
title: 'My Title'
description: "A thorough, yet succinct description of the page's contents"
---
```
The significant keys in the YAML frontmatter are:
- `title` `(string)` - This is the title of the page that will be set in the HTML title.
- `description` `(string)` - This is a description of the page that will be set in the HTML description.
> ⚠️ If there is a need for a `/api/*` url on this website, the url will be changed to `/api-docs/*`, as the `api` folder is reserved by next.js.
### Validating Content
Content changes are automatically validated against a set of rules as part of the pull request process. If you want to run these checks locally to validate your content before committing your changes, you can run the following command:
```
npm run content-check
```
If the validation fails, actionable error messages will be displayed to help you address detected issues.
### Creating New Pages
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
### Markdown Enhancements
There are several custom markdown plugins that are available by default that enhance [standard markdown](https://commonmark.org/) to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below:
- > **Warning**: We are deprecating the current [paragraph alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts), in favor of the newer [MDX Inline Alert](#inline-alerts) components. The legacy paragraph alerts are represented by the symbols `~>`, `->`, `=>`, or `!>`.
- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/content/partials` by default, and that changes to partials will not live-reload the website.
- If you see `# Headline ((#slug))`, this is an example of an [anchor link alias](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-link-aliases). It adds an extra permalink to a headline for compatibility and is removed from the output.
- Due to [automatically generated permalinks](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-links), any text changes to _headlines_ or _list items that begin with inline code_ can and will break existing permalinks. Be very cautious when changing either of these two text items.
Headlines are fairly self-explanatory, but here's an example of how to list items that begin with inline code look.
```markdown
- this is a normal list item
- `this` is a list item that begins with inline code
```
Its worth noting that _only the inline code at the beginning of the list item_ will cause problems if changed. So if you changed the above markup to...
```markdown
- lsdhfhksdjf
- `this` jsdhfkdsjhkdsfjh
```
...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to **avoid changing headlines and inline code at the start of a list item**. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible.
### Custom Components
A number of custom [mdx components](https://mdxjs.com/) are available for use within any `.mdx` file. Each one is documented below:
#### Inline Alerts
There are custom MDX components available to author alert data. [See the full documentation here](https://developer.hashicorp.com/swingset/components/mdxinlinealert). They render as colored boxes to draw the user's attention to some type of aside.
```mdx
## Alert types
### Tip
<Tip>
To provide general information to the user regarding the current context or
relevant actions.
</Tip>
### Highlight
<Highlight>
To provide general or promotional information to the user prominently.
</Highlight>
### Note
<Note>
To help users avoid an issue. Provide guidance and actions if possible.
</Note>
### Warning
<Warning>
To indicate critical issues that need immediate action or help users
understand something critical.
</Warning>
## Title override prop
<Note title="Hashiconf 2027">To provide general information.</Note>
```
#### Tabs
The `Tabs` component creates tabbed content of any type, but is often used for code examples given in different languages. Here's an example of how it looks from the Vagrant documentation website:
![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd)
> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documentation for the latest examples and API reference.
It can be used as such within a markdown file:
````mdx
Normal **markdown** content.
<Tabs>
<Tab heading="CLI command">
<!-- Intentionally skipped line.. -->
```shell-session
$ command ...
```
<!-- Intentionally skipped line.. -->
</Tab>
<Tab heading="API call using cURL">
```shell-session
$ curl ...
```
</Tab>
</Tabs>
Continued normal markdown content
````
The intentionally skipped line is a limitation of the mdx parser which is being actively worked on. All tabs must have a heading, and there is no limit to the number of tabs, though it is recommended to go for a maximum of three or four.
#### Enterprise Alert
This component provides a standard way to call out functionality as being present only in the enterprise version of the software. It can be presented in two contexts, inline or standalone. Here's an example of standalone usage from the Consul docs website:
![Enterprise Alert Component - Standalone](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALp8/Screen%20Shot%202020-06-11%20at%206.06.03%20PM.png?v=d1505b90bdcbde6ed664831a885ea5fb)
The standalone component can be used as such in markdown files:
```mdx
# Page Headline
<EnterpriseAlert />
Continued markdown content...
```
It can also receive custom text contents if you need to change the messaging but wish to retain the style. This will replace the text `This feature is available in all versions of Consul Enterprise.` with whatever you add. For example:
```mdx
# Page Headline
<EnterpriseAlert>
My custom text here, and <a href="#">a link</a>!
</EnterpriseAlert>
Continued markdown content...
```
It's important to note that once you are adding custom content, it must be html and can not be markdown, as demonstrated above with the link.
Now let's look at inline usage, here's an example:
![Enterprise Alert Component - Inline](https://p176.p0.n0.cdn.getcloudapp.com/items/L1upYLEJ/Screen%20Shot%202020-06-11%20at%206.07.50%20PM.png?v=013ba439263de8292befbc851d31dd78)
And here's how it could be used in your markdown document:
```mdx
### Some Enterprise Feature <EnterpriseAlert inline />
Continued markdown content...
```
It's also worth noting that this component will automatically adjust to the correct product colors depending on the context.
#### Other Components
Other custom components can be made available on a per-site basis, the above are the standards. If you have questions about custom components that are not documented here, or have a request for a new custom component, please reach out to @hashicorp/digital-marketing.
### Syntax Highlighting
When using fenced code blocks, the recommendation is to tag the code block with a language so that it can be syntax highlighted. For example:
````
```
// BAD: Code block with no language tag
```
```javascript
// GOOD: Code block with a language tag
```
````
Check out the [supported languages list](https://prismjs.com/#supported-languages) for the syntax highlighter we use if you want to double check the language name.
It is also worth noting specifically that if you are using a code block that is an example of a terminal command, the correct language tag is `shell-session`. For example:
🚫**BAD**: Using `shell`, `sh`, `bash`, or `plaintext` to represent a terminal command
````
```shell
$ terraform apply
```
````
✅**GOOD**: Using `shell-session` to represent a terminal command
````
```shell-session
$ terraform apply
```
````
<!-- END: editing-markdown -->
<!-- BEGIN: editing-docs-sidebars -->
<!-- Generated text, do not edit directly -->
## Editing Navigation Sidebars
The structure of the sidebars are controlled by files in the [`/data` directory](data). For example, [data/docs-nav-data.json](data/docs-nav-data.json) controls the **docs** sidebar. Within the `data` folder, any file with `-nav-data` after it controls the navigation for the given section.
The sidebar uses a simple recursive data structure to represent _files_ and _directories_. The sidebar is meant to reflect the structure of the docs within the filesystem while also allowing custom ordering. Let's look at an example. First, here's our example folder structure:
```text
.
├── docs
│   └── directory
│   ├── index.mdx
│   ├── file.mdx
│   ├── another-file.mdx
│   └── nested-directory
│   ├── index.mdx
│   └── nested-file.mdx
```
Here's how this folder structure could be represented as a sidebar navigation, in this example it would be the file `website/data/docs-nav-data.json`:
```json
[
{
"title": "Directory",
"routes": [
{
"title": "Overview",
"path": "directory"
},
{
"title": "File",
"path": "directory/file"
},
{
"title": "Another File",
"path": "directory/another-file"
},
{
"title": "Nested Directory",
"routes": [
{
"title": "Overview",
"path": "directory/nested-directory"
},
{
"title": "Nested File",
"path": "directory/nested-directory/nested-file"
}
]
}
]
}
]
```
A couple more important notes:
- Within this data structure, ordering is flexible, but hierarchy is not. The structure of the sidebar must correspond to the structure of the content directory. So while you could put `file` and `another-file` in any order in the sidebar, or even leave one or both of them out, you could not decide to un-nest the `nested-directory` object without also un-nesting it in the filesystem.
- The `title` property on each node in the `nav-data` tree is the human-readable name in the navigation.
- The `path` property on each leaf node in the `nav-data` tree is the URL path where the `.mdx` document will be rendered, and the
- Note that "index" files must be explicitly added. These will be automatically resolved, so the `path` value should be, as above, `directory` rather than `directory/index`. A common convention is to set the `title` of an "index" node to be `"Overview"`.
Below we will discuss a couple of more unusual but still helpful patterns.
### Index-less Categories
Sometimes you may want to include a category but not have a need for an index page for the category. This can be accomplished, but as with other branch and leaf nodes, a human-readable `title` needs to be set manually. Here's an example of how an index-less category might look:
```text
.
├── docs
│   └── indexless-category
│   └── file.mdx
```
```json
// website/data/docs-nav-data.json
[
{
"title": "Indexless Category",
"routes": [
{
"title": "File",
"path": "indexless-category/file"
}
]
}
]
```
### Custom or External Links
Sometimes you may have a need to include a link that is not directly to a file within the docs hierarchy. This can also be supported using a different pattern. For example:
```json
[
{
"name": "Directory",
"routes": [
{
"title": "File",
"path": "directory/file"
},
{
"title": "Another File",
"path": "directory/another-file"
},
{
"title": "Tao of HashiCorp",
"href": "https://www.hashicorp.com/tao-of-hashicorp"
}
]
}
]
```
If the link provided in the `href` property is external, it will display a small icon indicating this. If it's internal, it will appear the same way as any other direct file link.
<!-- END: editing-docs-sidebars -->
<!-- BEGIN: releases -->
<!-- Generated text, do not edit directly -->
## Changing the Release Version
To change the version displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_.
### Displaying a Prerelease
If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this:
```jsx
<ProductDownloader
product="<Product>"
version={VERSION}
downloads={downloadData}
community="/resources"
/>
```
To add a prerelease, an extra `prerelease` property can be added to the component as such:
```jsx
<ProductDownloader
product="<Product>"
version={VERSION}
downloads={downloadData}
community="/resources"
prerelease={{
type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
name: 'v1.0.0', // the name displayed in text on the website
version: '1.0.0-rc1', // the actual version tag that was pushed to releases.hashicorp.com
}}
/>
```
This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
```
A {{ release candidate }} for <Product> {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/<product>/{{ 1.0.0-rc1 }}'>downloaded here</a>.
```
You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` parameter from the above component.
<!-- END: releases -->
<!-- BEGIN: redirects -->
<!-- Generated text, do not edit directly -->
## Redirects
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects. It's important to note that redirects should only be used to cover for external links -- if you are moving a path which internal links point to, the internal links should also be adjusted to point to the correct page, rather than relying on a redirect.
To add a redirect, head over to the `redirects.js` file - the format is fairly simple - there's a `source` and a `destination` - fill them both in, indicate that it's a permanent redirect or not using the `permanent` key, and that's it. Let's look at an example:
```
{
source: '/foo',
destination: '/bar',
permanent: true
}
```
This redirect rule will send all incoming links to `/foo` to `/bar`. For more details on the redirects file format, [check out the docs on vercel](https://vercel.com/docs/configuration#project/redirects). All redirects will work both locally and in production exactly the same way, so feel free to test and verify your redirects locally. In the past testing redirects has required a preview deployment -- this is no longer the case. Please note however that if you add a redirect while the local server is running, you will need to restart it in order to see the effects of the redirect.
There is still one caveat though: redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such. The `.html` version is covered automatically.
```js
{ source: '/foo', destination: '/nested/foo', permanent: true }
```
Next, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like:
```js
{
category: 'docs',
content: [
'foo'
]
}
```
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destination, we need to slightly change the structure as such:
```js
{
category: 'docs',
content: [
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/<product>/foo' }
]
}
```
As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav.
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the redirects file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
<!-- END: redirects -->
<!-- BEGIN: browser-support -->
<!-- Generated text, do not edit directly -->
## Browser Support
We support the following browsers targeting roughly the versions specified.
| ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome.svg) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge.svg) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera.svg) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox.svg) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari.svg) |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Latest** | **Latest** | **Latest** | **Latest** | **Latest** |
<!-- END: browser-support -->
<!-- BEGIN: deployment -->
<!-- Generated text, do not edit directly -->
## Deployment
This website is hosted on Vercel and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews.
<!-- END: deployment -->
- For version-agnostic updates like typos, corrections, and broken links, submit
PRs against the `main` branch.

203
website/content/api-docs/auth/alicloud.mdx
View file

@ -1,203 +0,0 @@
---
layout: api
page_title: AliCloud - Auth Methods - HTTP API
description: This is the API documentation for the Vault AliCloud auth method.
---
> [!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.
# AliCloud auth method (API)
This is the API documentation for the Vault AliCloud auth method. For
general information about the usage and operation of the AliCloud method, please
see the [Vault AliCloud auth method documentation](/vault/docs/auth/alicloud).
This documentation assumes the AliCloud auth method is mounted at the `/auth/alicloud`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Create/Update role
Registers a role. Only entities using the role registered using this endpoint
will be able to perform the login operation.
| Method | Path |
| :----- | :-------------------------- |
| `POST` | `/auth/alicloud/role/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role. Must correspond with the name of the role reflected in the arn.
- `arn` `(string: <required>)` - The role's arn.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"arn": "acs:ram::5138828231865461:role/dev-role",
"policies": ["dev", "prod"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :-------------------------- |
| `GET` | `/auth/alicloud/role/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
```
### Sample response
```json
{
"data": {
"arn": "acs:ram::5138828231865461:role/dev-role",
"policies": ["default", "dev", "prod"],
"ttl": 1800000,
"max_ttl": 1800000,
"period": 0
}
}
```
## List roles
Lists all the roles that are registered with the method.
| Method | Path |
| :----- | :--------------------- |
| `LIST` | `/auth/alicloud/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/alicloud/roles
```
### Sample response
```json
{
"data": {
"keys": ["dev-role", "prod-role"]
}
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :-------------------------- |
| `DELETE` | `/auth/alicloud/role/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
```
## Login
Fetch a token. This endpoint verifies the signature of the signed
GetCallerIdentity request.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/auth/alicloud/login` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
- `identity_request_url` `(string: <required>)` - Base64-encoded HTTP URL used in
the signed request.
- `identity_request_headers` `(string: <required>)` - Base64-encoded,
JSON-serialized representation of the sts:GetCallerIdentity HTTP request
headers. The JSON serialization assumes that each header key maps to either a
string value or an array of string values (though the length of that array
will probably only be one).
### Sample payload
```json
{
"role": "dev-role",
"identity_request_url": "aWRlbnRpdHlabrVxdWVzdF91cmw=",
"identity_request_headers": "aWRlimRpdHlfcmVxdWVzdF9oZWFkZXJz"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/alicloud/login
```
### Sample response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1800000,
"metadata": {
"role_tag_max_ttl": "0",
"instance_id": "i-de0f1344",
"ami_id": "ami-fce36983",
"role": "dev-role",
"auth_type": "ec2",
"account_id": "5138828231865461",
"user_id": "216959339000654321",
"role_id": "4657-abcd",
"arn": "acs:ram::5138828231865461:assumed-role/dev-role/vm-ram-i-rj978rorvlg76urhqh7q",
"identity_type": "assumed-role",
"principal_id": "vm-ram-i-rj978rorvlg76urhqh7q",
"request_id": "D6E46F10-F26C-4AA0-BB69-FE2743D9AE62",
"role_name": "dev-role"
},
"policies": ["default", "dev"],
"accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
"client_token": "d9368254-3f21-aded-8a6f-7c818e81b17a"
}
}
```

719
website/content/api-docs/auth/approle.mdx
View file

@ -1,719 +0,0 @@
---
layout: api
page_title: AppRole - Auth Methods - HTTP API
description: This is the API documentation for the Vault AppRole auth method.
---
> [!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.
# AppRole auth method (API)
This is the API documentation for the Vault AppRole auth method. For
general information about the usage and operation of the AppRole method, please
see the [Vault AppRole method documentation](/vault/docs/auth/approle).
This documentation assumes the AppRole method is mounted at the `/auth/approle`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## List roles
This endpoint returns a list the existing AppRoles in the method.
| Method | Path |
| :----- | :------------------- |
| `LIST` | `/auth/approle/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/approle/role
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["dev", "prod", "test"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create/Update AppRole
Creates a new AppRole or updates an existing AppRole. This endpoint
supports both `create` and `update` capabilities. There can be one or more
constraints enabled on the role. It is required to have at least one of them
enabled while creating or updating a role.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes, accepted characters
include a-Z, 0-9, space, hyphen, underscore and periods.
- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when
logging in using this AppRole.
- `secret_id_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can perform the login
operation.
- `secret_id_num_uses` `(integer: 0)` - Number of times any particular SecretID
can be used to fetch a token from this AppRole, after which the SecretID by default
will expire. A value of zero will allow unlimited uses.
However, this option may be overridden by the request's 'num_uses' field when generating a SecretID.
- `secret_id_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which by default any SecretID
expires. A value of zero will allow the SecretID to not expire.
However, this option may be overridden by the request's 'ttl' field when generating a SecretID.
- `local_secret_ids` `(bool: false)` - If set, the secret IDs generated
using this role will be cluster local. This can only be set during role
creation and once set, it can't be reset later.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"token_type": "batch",
"token_ttl": "10m",
"token_max_ttl": "15m",
"token_policies": ["default"],
"period": 0,
"bind_secret_id": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
## Read AppRole
Reads the properties of an existing AppRole.
| Method | Path |
| :----- | :------------------------------ |
| `GET` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"token_ttl": 1200,
"token_max_ttl": 1800,
"secret_id_ttl": 600,
"secret_id_num_uses": 40,
"token_policies": ["default"],
"period": 0,
"bind_secret_id": true,
"secret_id_bound_cidrs": []
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete AppRole
Deletes an existing AppRole from the method.
| Method | Path |
| :------- | :------------------------------ |
| `DELETE` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
## Read AppRole role ID
Reads the RoleID of an existing AppRole.
| Method | Path |
| :----- | :-------------------------------------- |
| `GET` | `/auth/approle/role/:role_name/role-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Update AppRole role ID
Updates the RoleID of an existing AppRole to a custom value.
| Method | Path |
| :----- | :-------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/role-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `role_id` `(string: <required>)` - Value to be set as RoleID.
### Sample payload
```json
{
"role_id": "custom-role-id"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id
```
## Generate new secret ID
Generates and issues a new SecretID on an existing AppRole. Similar to
tokens, the response will also contain a `secret_id_accessor` value which can
be used to read the properties of the SecretID without divulging the SecretID
itself, and also to delete the SecretID from the AppRole.
| Method | Path |
| :----- | :---------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `metadata` `(string: "")` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks
enforcing secret IDs to be used from specific set of IP addresses. If
`secret_id_bound_cidrs` is set on the role, then the list of CIDR blocks listed
here should be a subset of the CIDR blocks listed on the role.
- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can use the auth tokens
generated by this SecretID. Overrides any role-set value but must be a subset.
- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which
the SecretID expires. A value of zero will allow unlimited uses.
Overrides secret_id_num_uses role option when supplied.
May not be higher than role's secret_id_num_uses.
- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`)
after which this SecretID expires. A value of zero will allow the SecretID to not expire.
Overrides secret_id_ttl role option when supplied.
May not be longer than role's secret_id_ttl.
### Sample payload
```json
{
"metadata": "{ \"tag1\": \"production\" }",
"ttl": 600,
"num_uses": 50
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9",
"secret_id_ttl": 600,
"secret_id_num_uses": 50
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List secret ID accessors
Lists the accessors of all the SecretIDs issued against the AppRole.
This includes the accessors for "custom" SecretIDs as well.
| Method | Path |
| :----- | :---------------------------------------- |
| `LIST` | `/auth/approle/role/:role_name/secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"ce102d2a-8253-c437-bf9a-aceed4241491",
"a1c8dee4-b869-e68d-3520-2040c1a0849a",
"be83b7e2-044c-7244-07e1-47560ca1c787",
"84896a0c-1347-aa90-a4f6-aca8b7558780",
"239b1328-6523-15e7-403a-a48038cdc45a"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read AppRole secret ID
Reads out the properties of a SecretID.
| Method | Path |
| :----- | :----------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id/lookup` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/lookup
```
### Sample Response
```json
{
"request_id": "74752925-f309-6859-3d2d-0fcded95150e",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"cidr_list": [],
"creation_time": "2023-02-10T18:17:27.089757383Z",
"expiration_time": "0001-01-01T00:00:00Z",
"last_updated_time": "2023-02-10T18:17:27.089757383Z",
"metadata": {
"tag1": "production"
},
"secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
"secret_id_num_uses": 0,
"secret_id_ttl": 0,
"token_bound_cidrs": []
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Destroy AppRole Secret ID
Destroy an AppRole secret ID.
| Method | Path |
| :----- | :------------------------------------------------ |
| `POST` | `/auth/approle/role/:role_name/secret-id/destroy` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/destroy
```
## Read AppRole secret ID accessor
Reads out the properties of a SecretID.
| Method | Path |
| :----- | :-------------------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/lookup` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/lookup
```
### Sample Response
```json
{
"request_id": "72836cd1-139c-fe66-1402-8bb5ca4044b8",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"cidr_list": [],
"creation_time": "2023-02-10T18:17:27.089757383Z",
"expiration_time": "0001-01-01T00:00:00Z",
"last_updated_time": "2023-02-10T18:17:27.089757383Z",
"metadata": {
"tag1": "production"
},
"secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
"secret_id_num_uses": 0,
"secret_id_ttl": 0,
"token_bound_cidrs": []
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Destroy AppRole Secret ID Accessor
Destroy an AppRole secret ID by its accessor.
| Method | Path |
| :----- | :--------------------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/destroy` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/destroy
```
## Create custom AppRole secret ID
Assigns a "custom" SecretID against an existing AppRole. This is used in the
"Push" model of operation.
| Method | Path |
| :----- | :----------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/custom-secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole. Must be less than 4096 bytes.
- `secret_id` `(string: <required>)` - SecretID to be attached to the Role.
- `metadata` `(string: "")` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks
enforcing secret IDs to be used from specific set of IP addresses. If
`secret_id_bound_cidrs` is set on the role, then the list of CIDR blocks listed
here should be a subset of the CIDR blocks listed on the role.
- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can use the auth tokens
generated by this SecretID. Overrides any role-set value but must be a subset.
- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which
the SecretID expires. A value of zero will allow unlimited uses.
Overrides secret_id_num_uses role option when supplied.
May not be higher than role's secret_id_num_uses.
- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`)
after which this SecretID expires. A value of zero will allow the SecretID to not expire.
Overrides secret_id_ttl role option when supplied.
May not be longer than role's secret_id_ttl.
### Sample payload
```json
{
"secret_id": "testsecretid",
"ttl": 600,
"num_uses": 50
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/custom-secret-id
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id": "testsecretid",
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id_ttl": 600,
"secret_id_num_uses": 50
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Login with AppRole
Issues a Vault token based on the presented credentials. `role_id` is always
required; if `bind_secret_id` is enabled (the default) on the AppRole,
`secret_id` is required too. Any other bound authentication values on the
AppRole (such as client IP CIDR) are also evaluated.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/auth/approle/login` |
### Parameters
- `role_id` `(string: <required>)` - RoleID of the AppRole.
- `secret_id` `(string: <required>)` - SecretID belonging to AppRole.
### Sample payload
```json
{
"role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8",
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/login
```
### Sample response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1200,
"metadata": null,
"token_policies": ["default"],
"accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374",
"client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49"
},
"warnings": null,
"wrap_info": null,
"data": null,
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read, update, or delete AppRole properties
Updates the respective property in the existing AppRole. All of these
parameters of the AppRole can be updated using the `/auth/approle/role/:role_name`
endpoint directly. The endpoints for each field is provided separately
to be able to delegate specific endpoints using Vault's ACL system.
| Method | Path |
| :---------------- | :---------------------------------------------------- | --------- |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/policies` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-num-uses` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-max-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/bind-secret-id` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-bound-cidrs` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-bound-cidrs` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/period` | `200/204` |
Refer to `/auth/approle/role/:role_name` endpoint.
## Tidy tokens
Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. Generally, running this is not needed unless upgrade
notes or support personnel suggest it. This may perform a lot of I/O to the
storage method so should be used sparingly.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/approle/tidy/secret-id` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/approle/tidy/secret-id
```
### Sample response
```json
{
"request_id": "b20b56e3-4699-5b19-cc6b-e74f7b787bbf",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": [
"Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs."
],
"auth": null
}
```

1422
website/content/api-docs/auth/aws.mdx
View file

File diff suppressed because it is too large Load diff

371
website/content/api-docs/auth/azure.mdx
View file

@ -1,371 +0,0 @@
---
layout: api
page_title: Azure - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault Azure authentication
method plugin.
---
> [!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.
# Azure auth method (API)
This is the API documentation for the Vault Azure auth method
plugin. To learn more about the usage and operation, see the
[Vault Azure method documentation](/vault/docs/auth/azure).
This documentation assumes the plugin method is mounted at the
`/auth/azure` path in Vault. Since it is possible to enable auth methods
at any location, please update your API calls accordingly.
## Configure
Configures the credentials required for the plugin to perform API calls
to Azure. These credentials will be used to query the metadata about the
virtual machine.
You can configure the auth engine with account credentials or plugin workload
identity federation (WIF).
| Method | Path |
| :----- | :------------------- |
| `POST` | `/auth/azure/config` |
### Parameters
- `tenant_id` `(string: <required>)` - The tenant id for the Azure Active Directory organization.
This value can also be provided with the `AZURE_TENANT_ID` environment variable.
- `resource` `(string: <required>)` - The resource URL for the application registered in Azure Active Directory.
The value is expected to match the audience (`aud` claim) of the [JWT](/vault/api-docs/auth/azure#jwt)
provided to the login API. See the [resource](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http)
parameter for how the audience is set when requesting a JWT access token from the Azure Instance Metadata Service (IMDS) endpoint.
This value can also be provided with the `AZURE_AD_RESOURCE` environment variable.
- `environment` `(string: 'AzurePublicCloud')` - The Azure cloud environment. Valid values: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud.
This value can also be provided with the `AZURE_ENVIRONMENT` environment variable.
- `client_id` `(string: '')` - The client id for credentials to query the Azure APIs. Currently read permissions to query compute resources are required.
This value can also be provided with the `AZURE_CLIENT_ID` environment variable.
- `client_secret` `(string: '')` - The client secret for credentials to query the Azure APIs.
This value can also be provided with the `AZURE_CLIENT_SECRET` environment variable.
Mutually exclusive with `identity_token_audience`.
- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
audience claim value for plugin identity tokens. Must match the allowed audiences configured
for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app).
Mutually exclusive with `client_secret`.
- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_retries` `(int: 3)` - The maximum number of attempts a failed operation will be
retried before producing an error.
- `max_retry_delay` `(string: '60s')` - The maximum delay, in seconds, allowed before retrying an operation.
- `retry_delay` `(string: '4s')` - The initial amount of delay, in seconds, to use before retrying an operation. Increases exponentially.
@include 'rotationfields.mdx'
### Sample payload
```json
{
"tenant_id": "kd83...",
"resource": "https://management.azure.com/",
"client_id": "12ud...",
"client_secret": "DUJDS3..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/azure/config
```
# Read config
Returns the previously configured config, including credentials.
| Method | Path |
| :----- | :------------------- |
| `GET` | `/auth/azure/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/azure/config
```
### Sample response
```json
{
"data":{
"tenant_id": "kd83...",
"resource": "https://management.azure.com/",
"client_id": "12ud...",
"client_secret": "DUJDS3..."
},
...
}
```
## Delete config
Deletes the previously configured Azure config and credentials.
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/auth/azure/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/auth/azure/config
```
## Rotate root
This endpoint generates a new client secret for the root account defined in the config. The
value generated will only be known by Vault.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/azure/rotate-root` |
### Parameters
There are no parameters to this operation.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/auth/azure/rotate-root
```
## Create/Update role
Registers a role in the method. Role types have specific entities
that can perform login operations against this endpoint. Constraints specific
to the role type must be set on the role. These are applied to the authenticated
entities attempting to login.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/auth/azure/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `bound_service_principal_ids` `(array: [])` - The list of Service Principal IDs
that login is restricted to. Either this parameter or `bound_group_ids` must be set.
- `bound_group_ids` `(array: [])` - The list of group ids that login is restricted
to. Either this parameter or `bound_service_principal_ids` must be set.
- `bound_locations` `(array: [])` - The list of locations that login is restricted to.
- `bound_subscription_ids` `(array: [])` - The list of subscription IDs that login
is restricted to.
- `bound_resource_groups` `(array: [])` - The list of resource groups that
login is restricted to.
- `bound_scale_sets` `(array: [])` - The list of scale set names that the
login is restricted to.
@include 'tokenfields.mdx'
~> **Note:** When creating a role, you must specify either `bound_service_principal_ids` or `bound_group_ids`. These parameters are mutually exclusive - you cannot set both, but you must set one of them.
### Sample payload
```json
{
"token_policies": ["default", "dev", "prod"],
"max_ttl": 1800000,
"max_jwt_exp": 10000,
"bound_resource_groups": ["vault-dev", "vault-staging", "vault-prod"],
"bound_service_principal_ids": ["3cb88732-1356-4782-b671-4877166be01a"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/azure/role/dev-role
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/auth/azure/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/azure/role/dev-role
```
### Sample response
```json
{
"data":{
"token_policies": [
"default",
"dev",
"prod"
],
"max_ttl": 1800000,
"max_jwt_exp": 10000,
"bound_resource_groups": [
"vault-dev",
"vault-staging",
"vault-prod"
]
},
...
}
```
## List roles
Lists all the roles that are registered with the plugin.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/auth/azure/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/auth/azure/role
```
### Sample response
```json
{
"data": {
"keys": [
"dev-role",
"prod-role"
]
},
...
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :----------------------- |
| `DELETE` | `/auth/azure/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/auth/azure/role/dev-role
```
## Login
Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
a role name for some entity. It verifies the JWT signature to authenticate that
entity and then authorizes the entity for the given role.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/auth/azure/login` |
### Sample payload
- `role` `(string: <required>)` - Name of the role against which the login is being
attempted.
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT)
from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token)
for details on how to acquire a JWT access token through instance metadata.
- `subscription_id` `(string: <required>)` - The subscription ID for the machine that
generated the MSI token. This information can be obtained through instance
metadata.
- `resource_group_name` `(string: <required>)` - The resource group for the machine that
generated the MSI token. This information can be obtained through instance
metadata.
- `vm_name` `(string: "")` - The virtual machine name for the machine that
generated the MSI token. This information can be obtained through instance
metadata. If `vmss_name` is provided, this value is ignored.
- `vmss_name` `(string: "")` - The virtual machine scale set name for the machine
that generated the MSI token. This information can be obtained through instance
metadata.
- `resource_id` `(string: "")` - The fully qualified ID of the Azure resource that
generated the MSI token, including the resource name and resource type. Use
the format /subscriptions/{guid}/resourceGroups/{resource-group-name}/{resource-provider-namespace}/{resource-type}/{resource-name}.
If `vm_name` or `vmss_name` is provided, this value is ignored.
### Sample payload
```json
{
"role": "dev-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/azure/login
```
### Sample response
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"token_policies":[
"default",
"dev",
"prod"
],
"lease_duration":2764800,
"renewable":true
},
...
}
```

451
website/content/api-docs/auth/cert.mdx
View file

@ -1,451 +0,0 @@
---
layout: api
page_title: TLS Certificate - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault TLS Certificate authentication
method.
---
> [!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.
# TLS certificate auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault TLS Certificate authentication
method. For general information about the usage and operation of the TLS
Certificate method, please see the [Vault TLS Certificate method documentation](/vault/docs/auth/cert).
This documentation assumes the TLS Certificate method is mounted at the
`/auth/cert` path in Vault. Since it is possible to enable auth methods at any
location, please update your API calls accordingly.
## Create CA certificate role
Sets a CA cert and associated parameters in a role name.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/auth/cert/certs/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
- `certificate` `(string: <required>)` - The PEM-format CA certificate.
- `allowed_names` `(string: "")` - DEPRECATED: Please use the individual
`allowed_X_sans` parameters instead. Constrain the Common and Alternative
Names in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of patterns. Authentication requires at least one Name
matching at least one pattern. If not set, defaults to allowing all names.
- `allowed_common_names` `(string: "" or array: [])` - Constrain the Common
Names in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of patterns. Authentication requires at least one Name
matching at least one pattern. If not set, defaults to allowing all names.
- `allowed_dns_sans` `(string: "" or array: [])` - Constrain the Alternative
Names in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of patterns. Authentication requires at least one DNS
matching at least one pattern. If not set, defaults to allowing all dns.
- `allowed_email_sans` `(string: "" or array: [])` - Constrain the Alternative
Names in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of patterns. Authentication requires at least one
Email matching at least one pattern. If not set, defaults to allowing all
emails.
- `allowed_uri_sans` `(string: "" or array: [])` - Constrain the Alternative
Names in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of URI patterns. Authentication requires at least one
URI matching at least one pattern. If not set, defaults to allowing all URIs.
- `allowed_organizational_units` `(string: "" or array: [])` - Constrain the
Organizational Units (OU) in the client certificate with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of OU patterns. Authentication requires at least one
OU matching at least one pattern. If not set, defaults to allowing all OUs.
- `required_extensions` `(string: "" or array: [])` - Require specific Custom
Extension OIDs to exist and match the pattern. Value is a comma separated
string or array of `oid:value`. Expects the extension value to be some type
of ASN1 encoded string. All conditions _must_ be met. To match on the hex-encoded
value of the extension, including non-string extensions, use the format
`hex:<oid>:<value>`.Supports globbing on `value`.
- `allowed_metadata_extensions` `(array:[])` - A comma separated string or
array of oid extensions. Upon successful authentication, these extensions
will be added as metadata if they are present in the certificate. The
metadata key will be the string consisting of the oid numbers separated
by a dash (-) instead of a dot (.) to allow usage in ACL templates.
- `ocsp_enabled` `(bool: false)` - If enabled, validate certificates' revocation
status using OCSP.
- `ocsp_ca_certificates` `(string: "")` Any additional OCSP responder certificates needed to
verify OCSP responses. Provided as base64 encoded PEM data.
- `ocsp_servers_override` `(array: [])`: A comma-separated list of OCSP server
addresses. If unset, the OCSP server is determined from the AuthorityInformationAccess
extension on the certificate being inspected.
- `ocsp_fail_open` `(bool: false)` - If true and an OCSP response cannot be fetched
or is of an unknown status, the login will proceed as if the certificate has not
been revoked.
- `ocsp_this_update_max_age` `(integer:0 or string: "")` - If greater than 0, specifies
the maximum age of an OCSP thisUpdate field. This avoids accepting old responses
without a nextUpdate field.
- `ocsp_max_retries` `(integer: 4)` - The number of retries attempted before giving
up on an OCSP request. 0 will disable retries
- `ocsp_query_all_servers` `(bool: false)` - If set to true, rather than accepting
the first successful OCSP response, query all servers and consider the certificate
valid only if all servers agree.
~> **Note**: When using Vault's PKI engine with Performance Replication clusters
as the OCSP provider, and without `unified_crls=true` set on the source mount
or when using cluster-local OCSP resolvers, we recommend enabling this option.
- `display_name` `(string: "")` - The `display_name` to set on tokens issued
when authenticating against this CA certificate. If not set, defaults to the
name of the role.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"display_name": "test",
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--cacert vault-ca.pem \
--data @payload.json
https://127.0.0.1:8200/v1/auth/cert/certs/test-ca
```
## Read CA certificate role
Gets information associated with the named role.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/auth/cert/certs/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/certs/test-ca
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"display_name": "test",
"policies": "",
"allowed_names": "",
"required_extensions": "",
"ttl": 2764800,
"max_ttl": 2764800,
"period": 0
},
"warnings": null,
"auth": null
}
```
## List certificate roles
Lists configured certificate names.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/auth/cert/certs` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/certs
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["cert1", "cert2"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete certificate role
Deletes the named role and CA cert from the method mount.
| Method | Path |
| :------- | :----------------------- |
| `DELETE` | `/auth/cert/certs/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/certs/cert1
```
## List CRLs
Lists configured certificate revocation lists.
| Method | Path |
| :----- | :---------------- |
| `LIST` | `/auth/cert/crls` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/crls
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["crl1", "crl2"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create CRL
Sets a named CRL.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/auth/cert/crls/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
- `crl` `(string: "")` - The PEM format CRL.
- `url` `(string: "")` - The URL of a CRL distribution point.
**Note**: Either 'crl' or 'url' parameters must be provided, if both are provided, 'crl' is used.
### Sample payload
```json
{
"crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--cacert vault-ca.pem \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl
```
## Read CRL
Gets information associated with the named CRL (currently, the serial
numbers contained within). As the serials can be integers up to an
arbitrary size, these are returned as strings.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/auth/cert/crls/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl
```
### Sample response
```json
{
"auth": null,
"data": {
"serials": {
"13": {}
}
},
"lease_duration": 0,
"lease_id": "",
"renewable": false,
"warnings": null
}
```
## Delete CRL
Deletes the named CRL from the auth method mount.
| Method | Path |
| :------- | :---------------------- |
| `DELETE` | `/auth/cert/crls/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
--cacert vault-ca.pem \
https://127.0.0.1:8200/v1/auth/cert/crls/cert1
```
## Configure TLS certificate method
Configuration options for the method.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/auth/cert/config` |
### Parameters
- `disable_binding` `(boolean: false)` - If set, during renewal, skips the
matching of presented client identity with the client identity used during
login.
- `enable_identity_alias_metadata` `(boolean: false)` - If set, metadata of
the certificate including the metadata corresponding to
`allowed_metadata_extensions` will be stored in the alias
- `ocsp_cache_size` `(int: 100)` - The size of the OCSP response LRU cache. Note
that this cache is used for all configured certificates.
- `role_cache_size` `(int: 200)` - The size of the role cache. Use `-1` to disable
role caching.
- `enable_metadata_on_failures` `(boolean: false)` - If set, metadata of the client
certificate such as common name, serial, subject key id and authority key id will
be returned on authentication failures and appear in auditing records.
### Sample payload
```json
{
"disable_binding": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--cacert vault-ca.pem \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/cert/config
```
## Login with TLS certificate method
Log in and fetch a token. If there is a valid chain to a CA configured in the
method and all role constraints are matched, a token will be issued. If the
certificate has DNS SANs in it, each of those will be verified. If Common Name
is required to be verified, then it should be a fully qualified DNS domain name
and must be duplicated as a DNS SAN (see
https://tools.ietf.org/html/rfc6125#section-2.3)
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/cert/login` |
### Parameters
- `name` `(string: "")` - Authenticate against only the named certificate role,
returning its policy list if successful. If not set, defaults to trying all
certificate roles and returning any one that matches.
### Sample payload
```json
{
"name": "cert1"
}
```
### Sample request
~> **NOTE** The `--cacert` value used here is for the Vault TLS Listener CA
certificate, not the CA that issued the client authentication certificate. This
can be omitted if the CA used to issue the Vault server certificate is trusted
by the local system executing this command.
```shell-session
$ curl \
--request POST \
--cacert vault-ca.pem \
--cert cert.pem \
--key key.pem \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/cert/login
```
### Sample response
```json
{
"auth": {
"client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425",
"policies": ["web", "stage"],
"lease_duration": 3600,
"renewable": true
}
}
```

343
website/content/api-docs/auth/cf.mdx
View file

@ -1,343 +0,0 @@
---
layout: api
page_title: Cloud Foundry - Auth Methods - HTTP API
description: This is the API documentation for the Vault Cloud Foundry auth method.
---
> [!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.
# Pivotal Cloud Foundry (CF) auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault CF auth method. For
general information about the usage and operation of the CF method, please
see the [Vault CF method documentation](/vault/docs/auth/cf).
This documentation assumes the CF method is mounted at the `/auth/cf`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Create configuration
Configure the root CA certificate to be used for verifying instance identity
certificates, and configure access to the CF API. For detailed instructions
on how to obtain these values, please see the [Vault CF method
documentation](/vault/docs/auth/cf).
| Method | Path |
| :----- | ----------------- |
| `POST` | `/auth/cf/config` |
### Parameters
- `identity_ca_certificates` `(array: [], required)` - The root CA certificate(s)
to be used for verifying that the `CF_INSTANCE_CERT` presented for logging in was
issued by the proper authority.
- `cf_api_addr` `(string: required)`: CF's full API address, to be used for verifying
that a given `CF_INSTANCE_CERT` shows an application ID, space ID, and organization ID
that presently exist.
- `cf_username` `(string: required)`: The username for authenticating to the CF API.
- `cf_password` `(string: required)`: The password for authenticating to the CF API.
- `cf_api_trusted_certificates` `(array: [])`: The certificate that's presented by the
CF API. This configures Vault to trust this certificate when making API calls, resolving
`x509: certificate signed by unknown authority` errors.
- `login_max_seconds_not_before` `(int: 300)`: The maximum number of seconds in the past when a
signature could have been created. The lower the value, the lower the risk of replay
attacks.
- `login_max_seconds_not_after` `(int: 60)`: In case of clock drift, the maximum number of
seconds in the future when a signature could have been created. The lower the value,
the lower the risk of replay attacks.
- `cf_timeout` `(duration: 0s)`: The timeout for the CF API. If not set, the default
timeout is 0, which means no timeout.
### Sample payload
```json
{
"identity_ca_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"cf_api_addr": "https://api.sys.somewhere.cf-app.com",
"cf_username": "vault",
"cf_password": "pa55w0rd",
"cf_api_trusted_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"login_max_seconds_not_before": 5,
"login_max_seconds_not_after": 1
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/config
```
## Read config
Returns the present CF configuration.
| Method | Path |
| :----- | ----------------- |
| `GET` | `/auth/cf/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/cf/config
```
### Sample response
```json
{
"identity_ca_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"cf_api_addr": "https://api.sys.somewhere.cf-app.com",
"cf_username": "vault",
"cf_api_trusted_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"login_max_seconds_not_before": 5,
"login_max_seconds_not_after": 1
}
```
## Delete config
Deletes the present CF configuration.
| Method | Path |
| :------- | ----------------- |
| `DELETE` | `/auth/cf/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/cf/config
```
## Create/Update role
Create a role in Vault granting a particular level of access to a particular group
of CF instances. We recommend using the CF API or the CF CLI to gain the IDs you
wish to target.
If you list no `bound` parameters, then any entity with a valid
`CF_INSTANCE_CERT` that's been issued by any configured `identity_ca_certificates`
will be able to authenticate against this role.
| Method | Path |
| :----- | ---------------------- |
| `POST` | `/auth/cf/roles/:role` |
### Parameters
- `role` `(string: required)` - The name of the role.
- `bound_application_ids` `(array: [])` - An optional list of application IDs
an instance must be a member of to qualify as a member of this role.
- `bound_space_ids` `(array: [])` - An optional list of space IDs
an instance must be a member of to qualify as a member of this role.
- `bound_organization_ids` `(array: [])` - An optional list of organization IDs
an instance must be a member of to qualify as a member of this role.
- `bound_instance_ids` `(array: [])` - An optional list of instance IDs
an instance must be a member of to qualify as a member of this role. Please note that
every time you use `cf push` on an app, its instance ID changes. Also, instance IDs
are not verifiable as being presently alive using the CF API. Thus, we recommend against
using this setting for most use cases.
- `disable_ip_matching` `(bool: false)` - If set to true, disables the default behavior
that logging in must be performed from an acceptable IP address described by the
certificate presented. Should only be set to true if required, generally when a proxy
is used to perform logins.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"],
"bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"],
"bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"],
"bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"],
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
"policies": ["default"],
"ttl": "1h",
"max_ttl": "1h",
"period": "1h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
## Read role
Returns a CF role.
| Method | Path |
| :----- | ---------------------- |
| `GET` | `/auth/cf/roles/:role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
### Sample response
```json
{
"bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"],
"bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"],
"bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"],
"bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"],
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
"policies": ["default"],
"ttl": 2764790,
"max_ttl": 2764790,
"period": 2764790
}
```
## Delete role
Deletes a CF role.
| Method | Path |
| :------- | ---------------------- |
| `DELETE` | `/auth/cf/roles/:role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
## List roles
Returns a CF role.
| Method | Path |
| :----- | ---------------- |
| `LIST` | `/auth/cf/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
http://127.0.0.1:8200/v1/auth/cf/roles
```
### Sample response
```json
{
"data": {
"keys": ["role1", "role2"]
}
}
```
## Login
Log in to CF.
Vault provides both an agent and a CLI tool for logging in that
eliminates the need to build a signature yourself. However, if you do wish to
build the signature, its signing algorithm is viewable [here](https://github.com/hashicorp/vault-plugin-auth-cf/tree/master/signatures).
The [plugin repo](https://github.com/hashicorp/vault-plugin-auth-cf) also contains
a command-line tool (`generate-signature`) that can be compiled as a binary for generating a signature,
and a test that outputs steps in generating the signature so they can be duplicated.
However, at a high level, these are the steps for generating a signature:
- Get and format the current time, ex. `2006-01-02T15:04:05Z`.
- Get the full body of the file located at `CF_INSTANCE_CERT`.
- Get the name of the role.
- Concatenate them together in the above order, with no extra string used for joining them.
- Create a SHA256 checksum of the resulting string (`checksum` below).
- Sign the string using the key located at `CF_INSTANCE_KEY`. In Go, this is performed using
the following line of code which you can more deeply inspect:
```
rsa.SignPSS(rand.Reader, rsaPrivateKey, crypto.SHA256, checksum, nil)
```
- Convert the signature to a string.
| Method | Path |
| :----- | ---------------- |
| `POST` | `/auth/cf/login` |
### Parameters
- `role` `(string: required)` - The name of the role.
- `cf_instance_cert` `(string: required)` - The full body of the file available at
the path denoted by `CF_INSTANCE_CERT`.
- `signing_time` `(string: required)` - The date and time used to construct the signature.
- `signature` `(string: required)` - The signature generated by the algorithm described
above using the `CF_INSTANCE_KEY`.
### Sample payload
```json
{
"role": "test-role",
"cf_instance_cert": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"signing_time": "2006-01-02T15:04:05Z",
"signature": "MmyUjQ1OqxQmF0W6raVQDL-hlqqe1oG-7abA6Oi3NHwT-9lMfrYxsCwMnd2HKGMly2tCgetcoA2orfquoe6MkMuksx_KGH_KLObcAykt53z4rHceHKGvm7eGj60cjWFYtiNPic-lzUGERLbUeKLMi6NlThm9ueb7hhpyTUpEYtphV3gorbVxvlkrnuYSbgy2NGpOUY1N8dRzcxmHkYjh12XoWEw4Is5aFr6eFKbZ0vmLWBzhJ7_w20CFyTpRYB-6heGz1iR9qEG8mZk3_x4rZpT5mejJ5zmH2xlUjBJMndfcz47btEi2BO9pFVxK2wK-tKeUUFgx6RcomAopTskkmg=="
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/login
```
### Sample response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1800000,
"policies": ["default", "dev"],
"accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
"client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
}
}
```

567
website/content/api-docs/auth/gcp.mdx
View file

@ -1,567 +0,0 @@
---
layout: api
page_title: Google Cloud - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault Google Cloud authentication
method.
---
> [!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.
# Google Cloud auth method (API)
This is the API documentation for the Vault Google Cloud auth method. To learn
more about the usage and operation, see the
[Vault Google Cloud method documentation](/vault/docs/auth/gcp).
This documentation assumes the plugin method is mounted at the
`/auth/gcp` path in Vault. Since it is possible to enable auth methods
at any location, please update your API calls accordingly.
## Configure
Configures the credentials required for the plugin to perform API calls
to Google Cloud. These credentials will be used to query the status of IAM
entities and get service account or other Google public certificates
to confirm signed JWTs passed in during login. You can configure
credentials either with Application Credentials for a privileged service account,
or using Plugin Workload Identity Federation (WIF).
### IAM
Vault uses the official Google Cloud SDK to source credentials from environment variables and shared files.
From the highest precedence to lowest, you can pass root credentials to the Vault server in the following ways:
1. Provide static credentials to the API as a payload.
1. Use [plugin workload identity federation](/vault/docs/auth/gcp#plugin-workload-identity-federation-wif) credentials.
1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
as environment variables on the Vault server.
<Warning title="Destructive action">
Passing Vault new root credentials overwrites any preexisting root credentials.
</Warning>
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/gcp/config` |
### Parameters
- `credentials` `(string: "")` - A JSON string containing the contents of a GCP
service account credentials file. The service account associated with the credentials
file must have the following [permissions](/vault/docs/auth/gcp#required-gcp-permissions).
If this value is empty, Vault will try to use [Application Default Credentials][gcp-adc]
from the machine on which the Vault server is running. Mutually exclusive with `identity_token_audience`.
@include 'rotationfields.mdx'
- `service_account_email` `(string: "")` – <EnterpriseAlert product="vault" inline /> Service Account
to impersonate for plugin workload identity federation. Required with `identity_token_audience`.
- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
audience claim value for plugin identity tokens. Must match an allowed audience configured
for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare).
Mutually exclusive with `credentials`.
- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `iam_alias` `(string: "role_id")` - Must be either `unique_id` or `role_id`.
If `unique_id` is specified, the service account's unique ID will be used for
alias names during login. If `role_id` is specified, the ID of the Vault role
will be used. Only used if role `type` is `iam`.
- `iam_metadata` `(string: "default")` - The metadata to include on the token
returned by the `login` endpoint. This metadata will be added to both audit logs,
and on the `iam_alias`. By default, it includes `project_id`, `role`,
`service_account_id`, and `service_account_email`. To include no metadata,
set to `""` via the CLI or `[]` via the API. To use only particular fields, select
the explicit fields. To restore to defaults, send only a field of `default`.
**Only select fields that will have a low rate of change** for your `iam_alias` because
each change triggers a storage write and can have a performance impact at scale.
Only used if role `type` is `iam`.
- `gce_alias` `(string: "role_id")` - Must be either `instance_id` or `role_id`.
If `instance_id` is specified, the GCE instance ID will be used for alias names
during login. If `role_id` is specified, the ID of the Vault role will be used.
Only used if role `type` is `gce`.
- `gce_metadata` `(string: "default")` - The metadata to include on the token
returned by the `login` endpoint. This metadata will be added to both audit logs,
and on the `gce_alias`. By default, it includes `instance_creation_timestamp`,
`instance_id`, `instance_name`, `project_id`, `project_number`, `role`,
`service_account_id`, `service_account_email`, and `zone`. To include no metadata,
set to `""` via the CLI or `[]` via the API. To use only particular fields, select
the explicit fields. To restore to defaults, send only a field of `default`.
**Only select fields that will have a low rate of change** for your `gce_alias` because
each change triggers a storage write and can have a performance impact at scale.
Only used if role `type` is `gce`.
- `custom_endpoint` `(map<string|string>: <optional>)` - Specifies overrides to
[service endpoints](https://cloud.google.com/apis/design/glossary#api_service_endpoint)
used when making API requests. This allows specific requests made during authentication
to target alternative service endpoints for use in [Private Google Access](https://cloud.google.com/vpc/docs/configure-private-google-access)
environments.
Overrides are set at the subdomain level using the following keys:
- `api` - Replaces the service endpoint used in API requests to `https://www.googleapis.com`.
- `iam` - Replaces the service endpoint used in API requests to `https://iam.googleapis.com`.
- `crm` - Replaces the service endpoint used in API requests to `https://cloudresourcemanager.googleapis.com`.
- `compute` - Replaces the service endpoint used in API requests to `https://compute.googleapis.com`.
The endpoint value provided for a given key has the form of `scheme://host:port`.
The `scheme://` and `:port` portions of the endpoint value are optional.
### Sample payload
```json
{
"credentials": "{ \"type\": \"service_account\", \"project_id\": \"project-123456\", ...}"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/config
```
## Rotate root credentials
Request to rotate the GCP service account credentials used by Vault
for this mount. A new key will be generated for the service account,
replacing the internal value, and then a deletion of the old service
account key is scheduled. Note that this does not create a new service
account, only a new version of the service account key.
This path is only valid if Vault has been configured to use GCP credentials via
the `config/` endpoint where "credentials" were specified. Additionally, the
provided service account must have permissions to create and delete service
account keys.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/gcp/config/rotate-root` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/auth/gcp/config/rotate-root
```
## Read config
| Method | Path |
| :----- | :----------------- |
| `GET` | `/auth/gcp/config` |
Credentials will be omitted from returned data.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/auth/gcp/config
```
### Sample response
```json
{
"data": {
"ttl": "1h",
"max_ttl": "4h"
}
}
```
## Read config
Returns the configuration, if any, including credentials.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/auth/gcp/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/gcp/config
```
### Sample response
```json
{
"data": {
"client_email": "service-account@project-123456.iam.gserviceaccount.com",
"client_id": "123456789101112131415",
"private_key_id": "97fd7ba59a96e1f3830296aedb4f50879e4d5382",
"project_id": "project-123456"
}
}
```
## Create/Update role
Registers a role in the method. Role types have specific entities
that can perform login operations against this endpoint. Constraints specific
to the role type must be set on the role. These are applied to the authenticated
entities attempting to login.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/auth/gcp/role/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the role.
- `type` `(string: <required>)` - The type of this role. Certain fields
correspond to specific roles and will be rejected otherwise. Please see below
for more information.
- `bound_service_accounts` `(array: <required for iam>)` - An array of
service account emails or IDs that login is restricted to,
either directly or through an associated instance. If set to
`*`, all service accounts are allowed (you can bind this further using
`bound_projects`.)
- `bound_projects` `(array: [])` - An array of GCP project IDs. Only entities
belonging to this project can authenticate under the role.
- `add_group_aliases` `(bool: false)` - If true, any auth token
generated under this token will have associated group aliases, namely
`project-$PROJECT_ID`, `folder-$PROJECT_ID`, and `organization-$ORG_ID`
for the entities project and all its folder or organization ancestors. This
requires Vault to have IAM permission `resourcemanager.projects.get`.
@include 'tokenfields.mdx'
#### `iam`-only parameters
The following parameters are only valid when the role is of type `"iam"`:
- `max_jwt_exp` `(string: "15m")` - The number of seconds past the time of
authentication that the login param JWT must expire within. For example, if a
user attempts to login with a token that expires within an hour and this is
set to 15 minutes, Vault will return an error prompting the user to create a
new signed JWT with a shorter `exp`. The GCE metadata tokens currently do not
allow the `exp` claim to be customized.
- `allow_gce_inference` `(bool: true)` - A flag to determine if this role should
allow GCE instances to authenticate by inferring service accounts from the
GCE identity metadata token.
#### `gce`-only parameters
The following parameters are only valid when the role is of type `"gce"`:
- `bound_zones` `(array: [])`: The list of zones that a GCE instance must belong
to in order to be authenticated. If `bound_instance_groups` is provided, it is
assumed to be a zonal group and the group must belong to this zone.
- `bound_regions` `(array: [])`: The list of regions that a GCE instance must
belong to in order to be authenticated. If `bound_instance_groups` is
provided, it is assumed to be a regional group and the group must belong to
this region. If `bound_zones` are provided, this attribute is ignored.
- `bound_instance_groups` `(array: [])`: The instance groups that an authorized
instance must belong to in order to be authenticated. If specified, either
`bound_zones` or `bound_regions` must be set too.
- `bound_labels` `(array: [])`: A comma-separated list of GCP labels formatted
as "key:value" strings that must be set on authorized GCE instances. Because
GCP labels are not currently ACL'd, we recommend that this be used in
conjunction with other restrictions.
### Sample payload
Example `iam` role:
```json
{
"type": "iam",
"project_id": "project-123456",
"policies": ["prod"],
"ttl": "30m",
"max_ttl": "24h",
"max_jwt_exp": "5m",
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"]
}
```
Example `gce` role:
```json
{
"type": "gce",
"project_id": "project-123456",
"policies": ["prod"],
"bound_zones": ["us-east1-b", "eu-west2-a"],
"ttl": "30m",
"max_ttl": "24h",
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Edit service accounts on IAM role
Edit service accounts for an existing IAM role in the method.
This allows you to add or remove service accounts from the list of
service accounts on the role.
| Method | Path |
| :----- | :-------------------------------------- |
| `POST` | `/auth/gcp/role/:name/service-accounts` |
### Parameters
- `name` `(string: <required>)` - The name of an existing `iam` type role. This
will return an error if role is not an `iam` type role.
- `add` `(array: [])` - The list of service accounts to add to the role's
service accounts.
- `remove` `(array: [])` - The list of service accounts to remove from the
role's service accounts.
### Sample payload
```json
{
"add": ["dev-1@project-123456.iam.gserviceaccount.com", "123456789"],
"remove": ["dev-2@project-123456.iam.gserviceaccount.com"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Edit labels on GCE role
Edit labels for an existing GCE role in the backend. This allows you to add or
remove labels (keys, values, or both) from the list of keys on the role.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/auth/gcp/role/:name/labels` |
### Parameters
- `name` `(string: <required>)` - The name of an existing `gce` role. This will
return an error if role is not a `gce` type role.
- `add` `(array: [])` - The list of `key:value` labels to add to the GCE role's
bound labels.
- `remove` `(array: [])` - The list of label _keys_ to remove from the role's
bound labels. If any of the specified keys do not exist, no error is returned
(idempotent).
### Sample payload
```json
{
"add": ["foo:bar", "env:dev", "key:value"],
"remove": ["key1", "key2"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `/auth/gcp/role/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the role to read.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
### Sample response
```json
{
"data": {
"bound_labels": {
"env": "dev",
"foo": "bar",
"key": "value"
},
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"],
"bound_zones": ["eu-west2-a", "us-east1-b"],
"gce_alias": "instance_id",
"max_ttl": 86400,
"policies": ["prod"],
"project_id": "project-123456",
"role_id": "6bbfab2b-ca32-6044-4829-4515728d87b1",
"type": "gce",
"ttl": 1800
}
}
```
## List roles
Lists all the roles that are registered with the plugin.
| Method | Path |
| :----- | :---------------- |
| `LIST` | `/auth/gcp/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/gcp/roles
```
### Sample response
```json
{
"data": {
"keys": ["my-role", "my-other-role"]
}
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :--------------------- |
| `DELETE` | `/auth/gcp/role/:role` |
### Parameters
- `role` `(string: <required>)` - The name of the role to delete.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Login
Login to retrieve a Vault token. This endpoint takes a signed JSON Web Token
(JWT) and a role name for some entity. It verifies the JWT signature with Google
Cloud to authenticate that entity and then authorizes the entity for the given
role.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/auth/gcp/login` |
### Sample payload
- `role` `(string: <required>)` - The name of the role against which the login
is being attempted.
- `jwt` `(string: <required>)` - A Signed [JSON Web Token][jwt].
- For `iam` type roles, this is a JWT signed with the
[`signJwt` method][signjwt-method] or a self-signed JWT.
- For `gce` type roles, this is an [identity metadata token][instance-token].
### Sample payload
```json
{
"role": "my-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/login
```
### Sample response
```json
{
"auth": {
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies": ["default", "dev", "prod"],
"metadata": {
"project_id": "my-project",
"role": "my-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
"lease_duration": 2764800,
"renewable": true
}
}
```
[gcp-adc]: https://developers.google.com/identity/protocols/application-default-credentials
[jwt]: https://tools.ietf.org/html/rfc7519
[signjwt-method]: https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signJwt
[instance-token]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature

281
website/content/api-docs/auth/github.mdx
View file

@ -1,281 +0,0 @@
---
layout: api
page_title: GitHub - Auth Methods - HTTP API
description: This is the API documentation for the Vault GitHub auth method.
---
> [!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.
# GitHub auth method (API)
This is the API documentation for the Vault GitHub auth method. For
general information about the usage and operation of the GitHub method, please
see the [Vault GitHub method documentation](/vault/docs/auth/github).
This documentation assumes the GitHub method is enabled at the `/auth/github`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Configure method
Configures the connection parameters for GitHub. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/auth/github/config` |
### Parameters
- `organization` `(string: <required>)` - The organization users must be part
of.
- `organization_id` `(int: 0)` - The ID of the organization users must be part
of. Vault will attempt to fetch and set this value if it is not provided.
- `base_url` `(string: "")` - The API endpoint to use. Useful if you are running
GitHub Enterprise or an API-compatible authentication server.
### Environment variables
- `VAULT_AUTH_CONFIG_GITHUB_TOKEN` `(string: "")` - An optional GitHub token used to make
authenticated GitHub API requests. This can be useful for bypassing GitHub's
rate-limiting during automation flows when the `organization_id` is not provided.
We encourage you to provide the `organization_id` instead of relying on this environment variable.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"organization": "acme-org"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/github/config
```
## Read configuration
Reads the GitHub configuration.
| Method | Path |
| :----- | :-------------------- |
| `GET` | `/auth/github/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/github/config
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"organization": "acme-org",
"base_url": "",
"ttl": "",
"max_ttl": ""
},
"warnings": null
}
```
## Map GitHub teams
Map a list of policies to a team that exists in the configured GitHub organization.
| Method | Path |
| :----- | :---------------------------------- |
| `POST` | `/auth/github/map/teams/:team_name` |
### Parameters
- `team_name` `(string)` - GitHub team name in "slugified" format
- `value` `(string)` - Comma separated list of policies to assign
### Sample payload
```json
{
"value": "dev-policy"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/github/map/teams/dev
```
## Read team mapping
Reads the GitHub team policy mapping.
| Method | Path |
| :----- | :---------------------------------- |
| `GET` | `/auth/github/map/teams/:team_name` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/github/map/teams/dev
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key": "dev",
"value": "dev-policy"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Map GitHub users
Map a list of policies to a specific GitHub user exists in the configured
organization.
| Method | Path |
| :----- | :---------------------------------- |
| `POST` | `/auth/github/map/users/:user_name` |
### Parameters
- `user_name` `(string)` - GitHub user name
- `value` `(string)` - Comma separated list of policies to assign
### Sample payload
```json
{
"value": "sethvargo-policy"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo
```
The user with username `sethvargo` will be assigned the `sethvargo-policy`
policy **in addition to** any team policies.
## Read user mapping
Reads the GitHub user policy mapping.
| Method | Path |
| :----- | :---------------------------------- |
| `GET` | `/auth/github/map/users/:user_name` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo
```
### Sample response
```json
{
"request_id": "764b6f88-efba-51bd-ed62-cf1c9e80e37a",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key": "sethvargo",
"value": "sethvargo-policy"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Login
Login using GitHub access token.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/auth/github/login` |
### Parameters
- `token` `(string: <required>)` - GitHub personal API token.
### Sample payload
```json
{
"token": "ABC123..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
http://127.0.0.1:8200/v1/auth/github/login
```
### Sample response
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "fred",
"org": "acme-org"
},
},
"lease_duration": 7200,
"renewable": true
}
```

20
website/content/api-docs/auth/index.mdx
View file

@ -1,20 +0,0 @@
---
layout: api
page_title: Auth Methods - HTTP API
description: |-
Each auth method publishes its own set of API paths and methods.
These endpoints are documented in this section.
---
> [!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.
# Auth methods
Each auth method publishes its own set of API paths and methods. These endpoints
are documented in this section. Auth methods are enabled at a path, but the
documentation will assume the default paths for simplicity. If you are enabling
at a different path, you should adjust your API calls accordingly.
For the API documentation for a specific auth method, please choose a auth
method from the navigation.

447
website/content/api-docs/auth/jwt.mdx
View file

@ -1,447 +0,0 @@
---
layout: api
page_title: JWT/OIDC - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault JWT/OIDC authentication
method plugin.
---
> [!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.
# JWT/OIDC auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault JWT/OIDC auth method
plugin. To learn more about the usage and operation, see the
[Vault JWT/OIDC method documentation](/vault/docs/auth/jwt).
This documentation assumes the plugin method is mounted at the
`/auth/jwt` path in Vault. Since it is possible to enable auth methods
at any location, please update your API calls accordingly.
## Configure
Configures the validation information to be used globally across all roles. One
(and only one) of `oidc_discovery_url`, `jwks_url`, and `jwt_validation_pubkeys` must be
set.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/jwt/config` |
### Parameters
- `oidc_discovery_url` `(string: <optional>)` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with "jwks_url" or "jwt_validation_pubkeys".
- `oidc_discovery_ca_pem` `(string: <optional>)` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used.
- `oidc_client_id` `(string: <optional>)` - The OAuth Client ID from the provider for OIDC roles.
- `oidc_client_secret` `(string: <optional>)` - The OAuth Client Secret from the provider for OIDC roles.
- `oidc_response_mode` `(string: <optional>)` - The response mode to be used in the OAuth2 request. Allowed values are "query" and "form_post". Defaults to "query". If using Vault namespaces, and oidc_response_mode is "form_post", then "namespace_in_state" should be set to false.
- `oidc_response_types` `(comma-separated string, or array of strings: <optional>)` - The response types to request. Allowed values are "code" and "id_token". Defaults to "code".
Note: "id_token" may only be used if "oidc_response_mode" is set to "form_post".
- `jwks_url` `(string: <optional>)` - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys".
- `jwks_ca_pem` `(string: <optional>)` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used.
- `jwks_pairs` `(list of JSON object: <optional>)` - List of JWKS URL and optional CA certificate pairs. CA certificates must be in PEM format. Must be a list of JSON objects with format `[{"jwks_url": "", "jwks_ca_pem": ""}]`. Cannot be used with "jwks_url" or "jwks_ca_pem".
- `jwt_validation_pubkeys` `(comma-separated string, or array of strings: <optional>)` - A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with "jwks_url" or "oidc_discovery_url".
- `bound_issuer` `(string: <optional>)` - The value against which to match the `iss` claim in a JWT. Cannot be configured when `jwks_pairs` is set.
- `jwt_supported_algs` `(comma-separated string, or array of strings: <optional>)` - A list of supported signing algorithms. Defaults to [RS256] for OIDC roles. Defaults to all [available algorithms](https://github.com/hashicorp/cap/blob/main/jwt/algs.go) for JWT roles.
- `default_role` `(string: <optional>)` - The default role to use if none is provided during login.
- `provider_config` `(map: <optional>)` - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in [OIDC Provider Setup](/vault/docs/auth/jwt/oidc-providers).
- `namespace_in_state` `(bool: true)` - Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in Vault and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs.
### Sample payload
```json
{
"oidc_discovery_url": "https://myco.auth0.com/",
"bound_issuer": "https://myco.auth0.com/"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/config
```
## Read config
Returns the previously configured config.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/auth/jwt/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/jwt/config
```
### Sample response
```json
{
"data":{
"oidc_discovery_url": "https://myco.auth0.com/",
"oidc_discovery_ca_pem": [],
"bound_issuer": "https://myco.auth0.com/",
"jwt_validation_pubkeys": []
},
...
}
```
## Create/Update role
Registers a role in the method. Role types have specific entities
that can perform login operations against this endpoint. Constraints specific
to the role type must be set on the role. These are applied to the authenticated
entities attempting to login. At least one of the bound values must be set.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/auth/jwt/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <optional>)` - List of `aud` claims to match against.
The `bound_audiences` parameter is required for "jwt" roles that contain an
audience (typical case) and **must** match at least one of the associated JWT
`aud` claims.
- `user_claim` `(string: <required>)` - The claim to use to uniquely identify
the user; this will be used as the name for the Identity entity alias created
due to a successful login. The claim value must be a string.
- `user_claim_json_pointer` `(bool: false)` - Specifies if the `user_claim` value uses
[JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for
referencing claims. By default, the `user_claim` value will not use JSON pointer.
- `clock_skew_leeway` `(int or string: <optional>)` - The amount of leeway to add to all claims to
account for clock skew, in seconds. Defaults to `60` seconds if set to `0` and can be disabled
if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
with "jwt" roles.
- `expiration_leeway` `(int or string: <optional>)` - The amount of leeway to add to expiration (`exp`) claims to
account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
with "jwt" roles.
- `not_before_leeway` `(int or string: <optional>)` - The amount of leeway to add to not before (`nbf`) claims to
account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
with "jwt" roles.
- `bound_subject` `(string: <optional>)` - If set, requires that the `sub`
claim matches this value.
- `bound_claims` `(map: <optional>)` - If set, a map of claims (keys) to match against respective claim values (values).
Each expected value may be a string, integer, boolean or a list of strings. The interpretation of the bound
claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
- `bound_claims_type` `(string: "string")` - Configures the interpretation of the bound_claims values.
If `"string"` (the default), the values will be treated as literals and must match exactly.
If set to `"glob"`, the values will be interpreted as globs, with `*` matching any number of
characters.
- `groups_claim` `(string: <optional>)` - The claim to use to uniquely identify
the set of groups to which the user belongs; this will be used as the names
for the Identity group aliases created due to a successful login. The claim
value must be a list of strings. Supports [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
- `claim_mappings` `(map: <optional>)` - If set, a map of claims (keys) to be copied to
specified metadata fields (values). Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
- `oidc_scopes` `(list: <optional>)` - If set, a list of OIDC scopes to be used with an OIDC role.
The standard scope "openid" is automatically included and need not be specified.
- `allowed_redirect_uris` `(list: <required>)` - The list of allowed values for redirect_uri
during OIDC logins.
- `verbose_oidc_logging` `(bool: false)` - Log received OIDC tokens and claims when debug-level
logging is active. Not recommended in production since sensitive information may be present
in OIDC responses.
- `max_age` `(int or string: <optional>)` - Specifies the allowable elapsed time in seconds since the last
time the user was actively authenticated with the OIDC provider. If set, the `max_age` request parameter
will be included in the authentication request. See [AuthRequest](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
for additional details. Accepts an integer number of seconds, or a Go duration format string.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"policies": ["dev", "prod"],
"bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
"bound_audiences": "https://myco.test",
"user_claim": "https://vault/user",
"groups_claim": "https://vault/groups",
"bound_claims": {
"department": "engineering",
"sector": "7g"
},
"claim_mappings": {
"preferred_language": "language",
"group": "group"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `/auth/jwt/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```
### Sample response
```json
{
"data":{
"bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
"bound_audiences": [
"https://myco.test"
],
"bound_cidrs": [],
"user_claim": "https://vault/user",
"groups_claim": "https://vault/groups",
"policies": [
"dev",
"prod"
],
"period": 0,
"ttl": 0,
"num_uses": 0,
"max_ttl": 0
},
...
}
```
## List roles
Lists all the roles that are registered with the plugin.
| Method | Path |
| :----- | :--------------- |
| `LIST` | `/auth/jwt/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/auth/jwt/role
```
### Sample response
```json
{
"data": {
"keys": [
"dev-role",
"prod-role"
]
},
...
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :--------------------- |
| `DELETE` | `/auth/jwt/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```
## OIDC authorization URL request
Obtain an authorization URL from Vault to start an OIDC login flow.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/jwt/oidc/auth_url` |
### Parameters
- `role` `(string: <optional>)` - Name of the role against which the login is being
attempted. Defaults to configured `default_role` if not provided.
- `redirect_uri` `(string: <required>)` - Path to the callback to complete the login. This will be
of the form, "https&#x3A;//.../oidc/callback" where the leading portion is dependent on your Vault
server location, port, and the mount of the JWT plugin. This must be configured with Vault and the
provider. See [Redirect URIs](/vault/docs/auth/jwt#redirect-uris) for more information.
- `client_nonce` `(string: <optional>)` - Optional client-provided nonce that
must match the `client_nonce` value provided during a subsequent request to the
[callback](/vault/api-docs/auth/jwt#oidc-callback) API.
### Sample payload
```json
{
"role": "dev-role",
"redirect_uri": "https://vault.myco.com:8200/ui/vault/auth/jwt/oidc/callback"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url
```
### Sample response
```json
{
"request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
"data": {
"auth_url": "https://myco.auth0.com/authorize?client_id=r3qXcK2bezU3Sbmh0K16fatW6&nonce=851b69a9bfa5a6a5668111314414e3687891a599&redirect_uri=https%3A%2F%2Fvault.myco.com3A8200%2Fui%2Fvault%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22"
},
...
}
```
## OIDC callback
Exchange an authorization code for an OIDC ID Token. The ID token will be further validated
against any bound claims, and if valid a Vault token will be returned.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/jwt/oidc/callback` |
### Parameters
- `state` `(string: <required>)` - Opaque state ID that is part of the Authorization URL and will
be included in the the redirect following successful authentication on the provider.
- `nonce` `(string: <required>)` - Opaque nonce that is part of the Authorization URL and will
be included in the the redirect following successful authentication on the provider.
- `code` `(string: <required>)` - Provider-generated authorization code that Vault will exchange for
an ID token.
- `client_nonce` `(string: <optional>)` - Optional client-provided nonce that must
match the `client_nonce` value provided during the prior request to the
[auth_url](/vault/api-docs/auth/jwt#oidc-authorization-url-request) API.
### Sample request
```shell-session
$ curl \
https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&nonce=ni42i2idj2jj
```
### Sample response
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"lease_duration":2764800,
"renewable":true
},
...
}
```
## JWT login
Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
a role name for some entity. It verifies the JWT signature to authenticate that
entity and then authorizes the entity for the given role.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/auth/jwt/login` |
### Parameters
- `role` `(string: <optional>)` - Name of the role against which the login is being
attempted. Defaults to configured `default_role` if not provided.
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT).
### Sample payload
```json
{
"role": "dev-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/login
```
### Sample response
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"lease_duration":2764800,
"renewable":true
},
...
}
```

413
website/content/api-docs/auth/kerberos.mdx
View file

@ -1,413 +0,0 @@
---
layout: api
page_title: Kerberos - Auth Methods - HTTP API
description: This is the API documentation for the Vault Kerberos auth method plugin.
---
> [!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.
# Kerberos auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault Kerberos auth method plugin. To
learn more about the usage and operation, see the
[Vault Kerberos auth method](/vault/docs/auth/kerberos).
This documentation assumes the Kerberos auth method is mounted at the
`auth/kerberos` path in Vault. Since it is possible to enable auth methods at
any location, please update your API calls accordingly.
The Kerberos auth method validates both Kerberos and LDAP authorization,
so both configurations are required.
## Configure Vault Kerberos
This endpoint configures the keytab and service account to be used by Vault
for verifying inbound SPNEGO tokens.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/auth/kerberos/config` |
- `keytab` `(string: <required>)` – A base 64 representation of the contents
of the Kerberos keytab that will be used for verifying inbound SPNEGO tokens.
It should contain an entry matching the service account given. This can be
created through the following command: `$ base64 vault.keytab > vault.keytab.base64`.
- `service_account` `(string: <required>)` – The service account associated
with both the keytab entry and an LDAP service account created for Vault. Ex.:
`"vault_svc"`.
- `remove_instance_name` - Removes any instance names from a Kerberos service
principal name when parsing the keytab file. For example when this is set to true,
if a keytab has the service principal name `foo/localhost@example.com`, Vault
will strip the service principal name to just be `foo@example.com`.
- `add_group_aliases` - When set to true, Vault will add any LDAP groups found for
the user as group aliases.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kerberos/config
```
### Sample payload
```json
{
"add_group_aliases": false,
"keytab": "BQIAAAA6AAEACk1BVFJJWC5MQU4ACXZhdWx0X3N2YwAAAAFdzZSjAgAXABDwhEyRR9nRqkpP8KTn2A83AAAAAg==",
"remove_instance_name": false,
"service_account": "vault_svc"
}
```
## Read Vault Kerberos
This endpoint retrieves the service account for the Kerberos auth method.
The keytab is not returned because it is sensitive information.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/auth/kerberos/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/kerberos/config
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"add_group_aliases": false,
"remove_instance_name": false,
"service_account": "vault_svc"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Configure Kerberos LDAP
This endpoint configures LDAP in the Kerberos auth method.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/kerberos/config/ldap` |
### Parameters
- `url` `(string: <required>)` – The LDAP server to connect to. Examples:
`ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. Multiple URLs can be
specified with commas, e.g. `ldap://ldap.myorg.com,ldap://ldap2.myorg.com`;
these will be tried in-order.
- `case_sensitive_names` `(bool: false)` – If set, user and group names
assigned to policies within the backend will be case sensitive. Otherwise,
names will be normalized to lower case. Case will still be preserved when
sending the username to the LDAP server at login time; this is only for
matching local user/group definitions.
- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after
establishing an unencrypted connection.
- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted
values are `tls10`, `tls11`, `tls12` or `tls13`.
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
values are `tls10`, `tls11`, `tls12` or `tls13`.
- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate
verification - insecure, use with caution!
- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server
certificate, must be x509 PEM encoded.
- `binddn` `(string: "")` – Distinguished name of object to bind when performing
user search. Example: `cn=vault,ou=Users,dc=example,dc=com`
- `bindpass` `(string: "")` – Password to use along with `binddn` when performing
user search.
- `userdn` `(string: "")` – Base DN under which to perform user search. Example:
`ou=Users,dc=example,dc=com`
- `userattr` `(string: "")` – Attribute on user attribute object matching the
username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid`
- `discoverdn` `(bool: false)` – Use anonymous bind to discover the bind DN of a
user.
- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing
authentication when providing an empty password.
- `upndomain` `(string: "")` – The _userPrincipalDomain_ used to construct the UPN
string for the authenticating user. The constructed UPN will appear as
`[username]@UPNDomain`. Example: `example.com`, which will cause vault to bind
as `username@example.com`.
- `groupfilter` `(string: "")` – Go template used when constructing the group
membership query. The template can access the following context variables:
\[`UserDN`, `Username`\]. The default is
`(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`,
which is compatible with several common directory schemas. To support
nested group resolution for Active Directory, instead use the following
query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`.
- `groupdn` `(string: "")` – LDAP search base to use for group membership
search. This can be the root containing either groups or users. Example:
`ou=Groups,dc=example,dc=com`
- `groupattr` `(string: "")` – LDAP attribute to follow on objects returned by
`groupfilter` in order to enumerate user group membership. Examples: for
groupfilter queries returning _group_ objects, use: `cn`. For queries
returning _user_ objects, use: `memberOf`. The default is `cn`.
@include 'tokenfields.mdx'
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kerberos/config/ldap
```
### Sample payload
```json
{
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"url": "ldaps://ldap.myorg.com:636",
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
}
```
## Read Kerberos LDAP configuration
This endpoint retrieves the LDAP configuration for the Kerberos auth method.
| Method | Path |
| :----- | :--------------------------- |
| `GET` | `/auth/kerberos/config/ldap` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/kerberos/config/ldap
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"bindpass": "",
"certificate": "",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"upndomain": "",
"url": "ldaps://ldap.myorg.com:636",
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List Kerberos LDAP groups
This endpoint returns a list of existing LDAP groups in the Kerberos auth method.
| Method | Path |
| :----- | :---------------------- |
| `LIST` | `/auth/kerberos/groups` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/kerberos/groups
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["scientists", "engineers"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read Kerberos LDAP group
This endpoint returns the policies associated with a Kerberos LDAP group.
| Method | Path |
| :----- | :---------------------------- |
| `GET` | `/auth/kerberos/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/kerberos/groups/admins
```
### Sample response
```json
{
"data": {
"policies": ["admin", "default"]
},
"renewable": false,
"lease_id": "",
"lease_duration": 0,
"warnings": null
}
```
## Create/Update Kerberos LDAP group
This endpoint creates or updates LDAP group policies.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/auth/kerberos/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group.
- `policies` `(string: "")` – Comma-separated list of policies associated to the
group.
### Sample payload
```json
{
"policies": "admin,default"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kerberos/groups/admins
```
## Delete Kerberos LDAP group
This endpoint deletes the LDAP group and policy association.
| Method | Path |
| :------- | :---------------------------- |
| `DELETE` | `/auth/kerberos/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/kerberos/groups/admins
```
## Login with Kerberos
This endpoint allows you to log in with a valid Kerberos SPNEGO
token. This token is obtained by the client, marshalled, and
converted to base 64 using standard encoding.
Example SPNEGO token (newlines added for readability):
```
YIIFSwYGKwYBBQUCoIIFPzCCBTugDTALBgkqhkiG9xIBAgKiggUoBIIFJGCCBSAGCSq
GSIb3EgECAgEAboIFDzCCBQugAwIBBaEDAgEOogcDBQAgAAAAo4IEB2GCBAMwggP/oA
MCAQWhDBsKTUFUUklYLkxBTqIvMC2gAwIBA6EmMCQbBEhUVFAbHDdlZmNjZTg4MGVkM
y5tYXRyaXgubGFuOjgyMDCjggO3MIIDs6ADAgEXoQMCAQKiggOlBIIDoXky+VDSMXqT
Z8XqUiIfzX3+t1ROgO49WYQPoqW1EJLA6vOVtsLITTuDUw8WaLIexki07up3wiO7bKn
unPFN3Y6VaKZfGoubVBFnLwrxqiEqytk19fiuc0bUJD5fNX+BUeHjePPmE73kRcuchC
L5+WkbY0X37cH5uKwCWI6TxpuEc74+mvmGOdAOdisC31MO6EBnOpTlxvKOXzShVk5Xa
rkkHjTJyjoUslgm8JVdj/uB/+x16k0bFVOuWybfeCkn4FY7OeIxypxDJgk6uHU+5jpy
XsdXK4w5GG+TK5BI6LXW8ZH6NOhcTZnRyt1/S4Wihd6HKhL8lH6H+wPWAnN4Ym8jiSg
7O0nIkp9su1l/umJWnLnyUdsC9ekKmCYS9MLrmaUREnKMFfrYOF283gWVmfuSWd832Q
9PIE93vUVTfetw1OwbJXEbG7ex3BotXPJ8yaDUAz4Zv0a6zQlj6JutE7LF3JvuuQeot
QnwPhrZTrmv7ZbmGO3GmkzbMzIwcTXCCKX8ocOo8GLmtEigAPK23FOW2Y0p1meYjF0U
xPzU6MPxfQWiXTWflqabXug7uZh8u76rzSEEceosPxoBqMm6hSmGc85+0bzy/E7AGJM
5ELa2Ny2KpyniPiYCap44GsFZbGM1FwJeh1bG3dJungIn7po4X2wlg00wZVlbHsBzhP
Hys0oxVzOQfrvx88G0fH80+vyzQiQAq4ZqmZqkO0zFSsdqG8ReJvpY0eGzN6/lGwcRl
eav7Vum/s5MalXhYUdOjB4K3A5yQArHbbLfeZlhb7d4vttzPNkmaZ9ZNTyW1GSuqDtd
+YJ0g70aN82KQMWiK3cbJcx/1jcmaN5gjSDm0xk19G2eb8VlRpwLFAazOlpPGozPl0Y
PD45h3Yv3AA5aMVXvEi+NvSYR3z9VXxk6A8wFJxV5NZxV2hYwmxt0S+TYXFeudXzT+W
ySoykcsxIU6rUevmJlEqZDyD3VcdnUOE9pxrIY/cqpdBBwatorF+jIK/ytcTBjvoM6c
LL4g4n/isWMu8Xs6lSMxZzrC3Ewv9VYMzOEFxaHUXlyIC8GCN6t9DHZNzT91TC0u5Rj
XuLqXENczg33dACvr+yhvin/0QNBQG+EXz/E4NiBBWqtTFa0BiTVTwyrKL5OyiLcIVe
v4l8l9vyj/ABwDacr9ZGjhFbOShCTuFFWBPNnBwPqiRBV4y1gPP4abYBmeboLrUiqwZ
81UrP2L8rCTEtYu9q3GmW/pIHqMIHnoAMCAReigd8EgdxwBViqyCyL0+J/k2bw0upNL
h+4wzJcFBFC/wxX2aMvvIYdQv5nWwdNLMII3l/zQ0+eRdzpKfg1ZRT6x0D5278eQLto
9r1CqKNW515u4kD5+pE8VOwZJMVe3FmduaH2gnTLAcoYXkBUE24hcr0ExSY6kTTBWPj
U5dsmUsj3+qrN9JruEADqw99t/EWnN3iTsHh1rOQOd9jIJ1wCIkgvnLB8Rad+q5jguG
8qQh1WDObTlNOnezDtiuLtRb03QDo8Q4Sm72IIcLDlffVvl7WAog5TpC8qM97+Wmv0C
sWw
```
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/auth/kerberos/login` |
### Sample request
```shell-session
$ curl \
--header "Authorization: Negotiate YIIFSw...sWw" \
--request POST \
http://127.0.0.1:8200/v1/auth/kerberos/login
```

347
website/content/api-docs/auth/kubernetes.mdx
View file

@ -1,347 +0,0 @@
---
layout: api
page_title: Kubernetes - Auth Methods - HTTP API
description: This is the API documentation for the Vault Kubernetes auth method plugin.
---
> [!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.
# Kubernetes auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault Kubernetes auth method plugin. To
learn more about the usage and operation, see the
[Vault Kubernetes auth method](/vault/docs/auth/kubernetes).
This documentation assumes the Kubernetes method is mounted at the
`/auth/kubernetes` path in Vault. Since it is possible to enable auth methods at
any location, please update your API calls accordingly.
## Configure method
The Kubernetes auth method validates service account JWTs and verifies their
existence with the Kubernetes TokenReview API. This endpoint configures the
public key used to validate the JWT signature and the necessary information to
access the Kubernetes API.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/kubernetes/config` |
### Parameters
- `kubernetes_host` `(string: <required>)` - Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server.
- `kubernetes_ca_cert` `(string: "")` - Optional PEM encoded CA cert that the TLS client can use to talk with the Kubernetes API.
**Every line must end with a newline `\n`.**
If `kubernetes_ca_cert` is unset, the TLS client uses the local CA cert if Vault is running in a Kubernetes pod.
If `kubernetes_ca_cert` is unset and `disable_local_ca_jwt` set to true, the TLS client uses the system's trusted CA certificate pool.
- `token_reviewer_jwt` `(string: "")` - A service account JWT (or other token) used as a bearer
token to access the TokenReview API to validate other JWTs during login. If not set,
the local service account token is used if running in a Kubernetes pod, otherwise
the JWT submitted in the login payload will be used to access the Kubernetes TokenReview API.
- `pem_keys` `(array: [])` - Optional list of PEM-formatted public keys or certificates
used to verify the signatures of Kubernetes service account
JWTs. If a certificate is given, its public key will be
extracted. Not every installation of Kubernetes exposes these
keys.
- `disable_local_ca_jwt` `(bool: false)` - Disable defaulting to the local CA cert and service account JWT when running in a Kubernetes pod.
- `use_annotations_as_alias_metadata` `(bool: false)` - Use annotations from the client token's associated service account
as alias metadata for the Vault entity. Only annotations with the
`vault.hashicorp.com/alias-metadata-` key prefix are targeted as alias metadata and
your annotations must be 512 characters or less due to the Vault alias
metadata value limit. For example, if you configure the annotation
`vault.hashicorp.com/alias-metadata-foo`, Vault saves the string "foo" along
with the annotation value to the alias metadata. **To save alias metadata,
Vault must have permission to read service accounts from the Kubernetes API**.
### Deprecated parameters
-> The following fields have been deprecated and will be removed in a future release:
- `disable_iss_validation` `(bool: true)` **Deprecated** Disable JWT issuer validation. Allows to skip ISS validation.
- `issuer` `(string: "")` **Deprecated** Optional JWT issuer. If no issuer is specified, then this plugin will use `kubernetes/serviceaccount` as the default issuer.
See [these instructions](/vault/docs/auth/kubernetes#discovering-the-service-account-issuer) for looking up the issuer for a given Kubernetes cluster.
### Caveats
If Vault is running in a Kubernetes Pod, the `kubernetes_ca_cert` and
`token_reviewer_jwt` parameters will automatically default to the local CA cert
(`/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`) and local service
account JWT (`/var/run/secrets/kubernetes.io/serviceaccount/token`).
If you override the default local CA cert behavior by setting `disable_local_ca_jwt` to `true`,
the plugin's TLS client will automatically default to using the system's trust store for TLS certificate verification.
### Sample payload
```json
{
"kubernetes_host": "https://192.168.99.100:8443",
"kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----",
"pem_keys": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kubernetes/config
```
## Read config
Returns the previously configured config, excluding credentials.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/kubernetes/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/kubernetes/config
```
### Sample response
```json
{
"data":{
"kubernetes_host": "https://192.168.99.100:8443",
"kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----",
"pem_keys": ["-----BEGIN CERTIFICATE-----.....", .....],
"disable_local_ca_jwt": false,
"token_reviewer_jwt_set": false
}
}
```
## Create/Update role
Registers a role in the auth method. Role types have specific entities
that can perform login operations against this endpoint. Constraints specific
to the role type must be set on the role. These are applied to the authenticated
entities attempting to login.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/auth/kubernetes/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `bound_service_account_names` `(array: <required>)` - List of service account
names able to access this role. If set to "\*" all names are allowed.
- `bound_service_account_namespaces` `(array: [])` - List of namespaces
allowed to access this role. If set to "\*" all namespaces are allowed.
- `bound_service_account_namespace_selector` `(string: "")` - A label selector for Kubernetes
namespaces allowed to access this role. Accepts either a JSON or YAML object. The value
should be of type
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta). Currently, label selectors with `matchExpressions` are not supported.
To use label selectors, **Vault must have permission to read namespaces** on the Kubernetes
cluster. If set with `bound_service_account_namespaces`, the conditions are `OR`ed.
- `audience` `(string: "")` - Audience claim to verify in the JWT. Will be required in Vault 1.21+.
- `alias_name_source` `(string: "serviceaccount_uid")` - Configures how identity aliases are generated.
Valid choices are: `serviceaccount_uid` and `serviceaccount_name`.
When you specify `serviceaccount_uid`, Vault uses a machine generated UID from
the service account as the identity alias name. Using a service account UID is
both the default and the recommended method as it the more secure option.
When you specify `serviceaccount_name`, Vault uses the name and namespace from
the service account as the identity alias name (e.g., `vault/vault-auth`). You
should only use `serviceaccount_name` if you consider the risk acceptable or
can mitigate the risk with strong controls around the creation/deletion/access
of your Kubernetes service accounts and need one of the following capabilities:
1. fine-grained control over the mapping between Kubernetes service accounts
and Vault identities.
1. a simpler process for setting entity aliases before creating Kubernetes
service account creation.
See the [Create an Entity Alias](/vault/api-docs/secret/identity/entity-alias#create-an-entity-alias) document
which further expands on the potential security implications mentioned above.
@include 'tokenfields.mdx'
### Sample Payload 1
```json
{
"bound_service_account_names": "vault-auth",
"bound_service_account_namespaces": "default",
"policies": ["dev", "prod"],
"max_ttl": 1800000
}
```
### Sample Payload 2
```json
{
"bound_service_account_names": "vault-auth",
"bound_service_account_namespace_selector": "\"{\"matchLabels\":{\"stage\":\"dev\",\"vault-role\":\"dev-role\"}}",
"policies": ["dev", "prod"],
"max_ttl": 1800000
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :---------------------------- |
| `GET` | `/auth/kubernetes/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role
```
### Sample response
```json
{
"data": {
"bound_service_account_names": "vault-auth",
"bound_service_account_namespaces": "default",
"max_ttl": 1800000,
"ttl": 0,
"period": 0,
"policies": ["dev", "prod"]
}
}
```
## List roles
Lists all the roles that are registered with the auth method.
| Method | Path |
| :----- | :-------------------------------- |
| `LIST` | `/auth/kubernetes/role` |
| `GET` | `/auth/kubernetes/role?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/kubernetes/role
```
### Sample response
```json
{
"data": {
"keys": ["dev-role", "prod-role"]
}
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :---------------------------- |
| `DELETE` | `/auth/kubernetes/role/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role
```
## Login
Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
a role name for some entity. It verifies the JWT signature to authenticate that
entity and then authorizes the entity for the given role.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/auth/kubernetes/login` |
### Parameters
- `role` `(string: <required>)` - Name of the role against which the login is being
attempted.
- `jwt` `(string: <required>)` - Signed [JSON Web
Token](https://tools.ietf.org/html/rfc7519) (JWT) for authenticating a service
account.
### Sample payload
```json
{
"role": "dev-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kubernetes/login
```
### Sample response
```json
{
"auth": {
"client_token": "62b858f9-529c-6b26-e0b8-0457b6aacdb4",
"accessor": "afa306d0-be3d-c8d2-b0d7-2676e1c0d9b4",
"policies": ["default"],
"metadata": {
"role": "test",
"service_account_name": "vault-auth",
"service_account_namespace": "default",
"service_account_secret_name": "vault-auth-token-pd21c",
"service_account_uid": "aa9aa8ff-98d0-11e7-9bb7-0800276d99bf"
},
"lease_duration": 2764800,
"renewable": true
}
}
```

500
website/content/api-docs/auth/ldap.mdx
View file

@ -1,500 +0,0 @@
---
layout: api
page_title: LDAP - Auth Methods - HTTP API
description: This is the API documentation for the Vault LDAP auth method.
---
> [!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.
# LDAP auth method (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault LDAP auth method. For
general information about the usage and operation of the LDAP method, please
see the [Vault LDAP method documentation](/vault/docs/auth/ldap).
This documentation assumes the LDAP method is mounted at the `/auth/ldap`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Configure LDAP
This endpoint configures the LDAP auth method.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/auth/ldap/config` |
### Parameters
- `url` `(string: ldap://127.0.0.1)` – The LDAP server to connect to. Examples:
`ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. Multiple URLs can be
specified with commas, e.g. `ldap://ldap.myorg.com,ldap://ldap2.myorg.com`;
these will be tried in-order.
- `case_sensitive_names` `(bool: false)` – If set, user and group names
assigned to policies within the backend will be case sensitive. Otherwise,
names will be normalized to lower case. Case will still be preserved when
sending the username to the LDAP server at login time; this is only for
matching local user/group definitions.
- `connection_timeout` `(integer: 30 or string: "30s")` - Timeout, in seconds,
when attempting to connect to the LDAP server before trying the next URL in
the configuration.
- `request_timeout` `(integer: 90 or string: "90s")` - Timeout, in seconds, for
the connection when making requests against the server before returning back
an error.
- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after
establishing an unencrypted connection.
- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted
values are `tls10`, `tls11`, `tls12` or `tls13`.
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
values are `tls10`, `tls11`, `tls12` or `tls13`.
- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate
verification - insecure, use with caution!
- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server
certificate, must be x509 PEM encoded.
- `client_tls_cert` `(string "")` - Client certificate to provide to the LDAP
server, must be x509 PEM encoded (optional).
- `client_tls_key` `(string "")` - Client certificate key to provide to the LDAP
server, must be x509 PEM encoded (optional).
- `binddn` `(string: "")` – Distinguished name of object to bind when performing
user search. Example: `cn=vault,ou=Users,dc=example,dc=com`
- `bindpass` `(string: "")` – Password to use along with `binddn` when performing
user search.
- `userdn` `(string: "")` – Base DN under which to perform user search. Example:
`ou=Users,dc=example,dc=com`
- `userattr` `(string: "cn")` – Attribute on user attribute object matching the
username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid`
- `discoverdn` `(bool: false)` – Use anonymous bind to discover the bind DN of a
user.
- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing
authentication when providing an empty password.
- `upndomain` `(string: "")` – The userPrincipalDomain used to construct the UPN
string for the authenticating user. The constructed UPN will appear as
`[username]@UPNDomain`. Example: `example.com`, which will cause vault to bind
as `username@example.com`.
- `userfilter` `(string: "")` – An optional LDAP user search filter.
The template can access the following context variables: UserAttr, Username.
The default is `({{.UserAttr}}={{.Username}})`, or `({{.UserAttr}}={{.Username@.upndomain}})`
if `upndomain` is set. In order for the `userfilter` to be applied,
both `binddn` and `bindpass` must be set, or `discoverdn` must be set to `true`.
- `anonymous_group_search` `(bool: false)` - Use anonymous binds when performing
LDAP group searches (note: even when `true`, the initial credentials will still
be used for the initial connection test).
- `groupfilter` `(string: "")` – Go template used when constructing the group
membership query. The template can access the following context variables:
\[`UserDN`, `Username`\]. The default is
`(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`,
which is compatible with several common directory schemas. To support
nested group resolution for Active Directory, instead use the following
query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`.
- `groupdn` `(string: "")` – LDAP search base to use for group membership
search. This can be the root containing either groups or users. Example:
`ou=Groups,dc=example,dc=com`
- `groupattr` `(string: "")` – LDAP attribute to follow on objects returned by
`groupfilter` in order to enumerate user group membership. Examples: for
groupfilter queries returning _group_ objects, use: `cn`. For queries
returning _user_ objects, use: `memberOf`. The default is `cn`.
- `username_as_alias` `(bool: false)` - If set to true, forces the auth method
to use the username passed by the user as the alias name.
- `dereference_aliases` `(string: never)` - When aliases should be dereferenced
on search operations. Accepted values are 'never', 'finding', 'searching',
'always'. Defaults to 'never'.
- `max_page_size` `(int: 0)` - If set to a value greater than 0, the LDAP
backend will use the LDAP server's paged search control to request pages of
up to the given size. This can be used to avoid hitting the LDAP server's
maximum result size limit. Otherwise, the LDAP backend will not use the
paged search control.
- `use_token_groups` `(bool: true)` - (Optional) Use the Active Directory tokenGroups
constructed attribute of the user to find the group memberships.
- `enable_samaccountname_login` `(bool: false)` - (Optional) Lets Active Directory
LDAP users log in using `sAMAccountName` or `userPrincipalName` when the
`upndomain` parameter is set.
@include 'rotationfields.mdx'
@include 'tokenfields.mdx'
@include 'ldap-auth-userfilter-warning.mdx'
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/config
```
### Sample payload
```json
{
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"url": "ldaps://ldap.myorg.com:636",
"username_as_alias": false,
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com",
"max_page_size": 1000
}
```
## Read LDAP configuration
This endpoint retrieves the LDAP configuration for the auth method.
| Method | Path |
| :----- | :------------------ |
| `GET` | `/auth/ldap/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/config
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"bindpass": "",
"certificate": "",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"upndomain": "",
"url": "ldaps://ldap.myorg.com:636",
"username_as_alias": false,
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List LDAP groups
This endpoint returns a list of existing groups in the method.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `/auth/ldap/groups` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/ldap/groups
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["scientists", "engineers"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read LDAP group
This endpoint returns the policies associated with a LDAP group.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/ldap/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
```
### Sample response
```json
{
"data": {
"policies": [
"admin",
"default"
]
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
## Create/Update LDAP group
This endpoint creates or updates LDAP group policies.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/ldap/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
- `policies` `(string: "")` – Comma-separated list of policies associated to the
group.
### Sample payload
```json
{
"policies": "admin,default"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
```
## Delete LDAP group
This endpoint deletes the LDAP group and policy association.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/auth/ldap/groups/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
```
## List LDAP users
This endpoint returns a list of existing users in the method.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/auth/ldap/users` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/ldap/users
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["mitchellh", "armon"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read LDAP user
This endpoint returns the policies associated with a LDAP user.
| Method | Path |
| :----- | :--------------------------- |
| `GET` | `/auth/ldap/users/:username` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh
```
### Sample response
```json
{
"data": {
"policies": [
"admin",
"default"
],
"groups": ""
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
## Create/Update LDAP user
This endpoint creates or updates LDAP users policies and group associations.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/ldap/users/:username` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
- `policies` `(string: "")` – Comma-separated list of policies associated to the
user.
- `groups` `(string: "")` – Comma-separated list of groups associated to the
user.
### Sample payload
```json
{
"policies": "admin,default"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh
```
## Delete LDAP user
This endpoint deletes the LDAP user and policy association.
| Method | Path |
| :------- | :--------------------------- |
| `DELETE` | `/auth/ldap/users/:username` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh
```
## Login with LDAP user
This endpoint allows you to log in with LDAP credentials
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/ldap/login/:username` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
- `password` `(string: <required>)` – The password for the LDAP user.
When authenticating with the Vault CLI, i.e. `vault login -method=ldap username=mitchellh`
the password can alternatively be supplied via the `VAULT_LDAP_PASSWORD` environment variable.
### Sample payload
```json
{
"password": "MyPassword1"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/login/mitchellh
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": ["admins", "default"],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 0,
"renewable": false
}
}
```

246
website/content/api-docs/auth/oci.mdx
View file

@ -1,246 +0,0 @@
---
layout: api
page_title: OCI - Auth Methods - HTTP API
description: This is the API documentation for the Vault OCI auth method plugin.
---
> [!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.
# OCI auth method (API)
This is the API documentation for the Vault OCI auth method plugin. To
learn more about the usage and operation, see the
[Vault OCI auth method](/vault/docs/auth/oci).
This documentation assumes the OCI method is mounted at the
`/auth/oci` path in Vault. Since it is possible to enable auth methods at
any location, please update your API calls accordingly.
## Configure home tenancy method
Configure your home tenancy in the Vault, so that only users or instances from your tenancy will be allowed to log into Vault, through the OCI Auth method.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/oci/config` |
### Parameters
- `home_tenancy_id` `(string: <required>)` - The Tenancy OCID of your OCI account.
### Sample payload
```json
{
"home_tenancy_id": "ocid1.tenancy.oc1..aaaaaaaah7zkvaffv26pzyauoe2zbnionqvhvsexamplee557wakiofi4ysgqq"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/oci/config
```
## Read config
Returns the previously configured config.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/auth/oci/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/oci/config
```
### Sample response
```json
{
"data": {
"home_tenancy_id": "ocid1.tenancy.oc1..aaaaaaaah7zkvaffv26pzyauoe2zbnionqvhvsexamplee557wakiofi4ysgqq"
}
}
```
## Create/Update role
Create a Vault administrator role in the OCI Auth method.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/auth/oci/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `ocid_list` `(string: <required>)` - A comma separated list of Group or Dynamic Group OCIDs that can take this role.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"ocid_list": "ocid1.group.oc1..aaaaaaaaiqnblimpvmegkqh3bxilrdvjobr7qd223g275idcqhexamplefq,ocid1.dynamicgroup.oc1..aaaaaaaa5hmfyrdaxvmt52ekju5n7ffamn2pdvxaq6esb2vzzoduexamplea",
"token_policies": ["dev", "prod"],
"token_ttl": 1800
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/oci/role/devrole
```
## Read role
Returns the previously registered role configuration.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `/auth/oci/role/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/oci/role/devrole
```
### Sample response
```json
{
"data": {
"ocid_list": [
"ocid1.group.oc1..aaaaaaaaiqnblimpvmegkqh3bxilrdvjobr7qd223g275idcqhexamplefq",
"ocid1.dynamicgroup.oc1..aaaaaaaa5hmfyrdaxvmt52ekju5n7ffamn2pdvxaq6esb2vzzoduexamplea"
],
"token_ttl": 1800,
"token_policies": ["dev", "prod"]
}
}
```
## List roles
Lists all the roles that are registered with the auth method.
| Method | Path |
| :----- | :------------------------- |
| `LIST` | `/auth/oci/role` |
| `GET` | `/auth/oci/role?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/oci/role
```
### Sample response
```json
{
"data": {
"keys": ["devrole", "prodrole"]
}
}
```
## Delete role
Deletes the previously registered role.
| Method | Path |
| :------- | :--------------------- |
| `DELETE` | `/auth/oci/role/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/oci/role/devrole
```
## Login
Fetch a token. This endpoint takes signed request headers and
a role name for some entity. It verifies the signed request headers to authenticate that
entity and then authorizes the entity for the given role.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/auth/oci/login/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role against which the login is being attempted.
- `request_headers` `(list: [])` - Signed request headers for authenticating. For details on signing, see [signing the request](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/signingrequests.htm)
### Sample payload
```json
{
"request_headers": {
"date": ["Fri, 22 Aug 2019 21:02:19 GMT"],
"(request-target)": ["get /v1/auth/oci/login/devrole"],
"host": ["127.0.0.1"],
"content-type": ["application/json"],
"authorization": [
"Signature algorithm=\"rsa-sha256\",headers=\"date (request-target) host\",keyId=\"ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/73:61:a2:21:67:e0:df:be:7e:4b:93:1e:15:98:a5:b7\",signature=\"GBas7grhyrhSKHP6AVIj/h5/Vp8bd/peM79H9Wv8kjoaCivujVXlpbKLjMPeDUhxkFIWtTtLBj3sUzaFj34XE6YZAHc9r2DmE4pMwOAy/kiITcZxa1oHPOeRheC0jP2dqbTll8fmTZVwKZOKHYPtrLJIJQHJjNvxFWeHQjMaR7M=\",version=\"1\""
]
}
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/oci/login/devrole
```
### Sample response
```json
{
"auth": {
"token": "62b8ssf9-529c-6b26-e0b8-045fcdb4",
"token_accessor": "afaff6d0-be3d-c8d2-b0d7-2676sss0d9b4",
"token_policies": ["dev"],
"token_duration": 1800
}
}
```

437
website/content/api-docs/auth/okta.mdx
View file

@ -1,437 +0,0 @@
---
layout: api
page_title: Okta - Auth Methods - HTTP API
description: This is the API documentation for the Vault Okta auth method.
---
> [!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.
# Okta auth method (API)
This is the API documentation for the Vault Okta auth method. For
general information about the usage and operation of the Okta method, please
see the [Vault Okta method documentation](/vault/docs/auth/okta).
This documentation assumes the Okta method is mounted at the `/auth/okta`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Create configuration
Configures the connection parameters for Okta. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/auth/okta/config` |
### Parameters
- `org_name` `(string: <required>)` - Name of the organization to be used in the
Okta API.
- `api_token` `(string: "")` - Okta API token. This is required to query Okta
for user group membership. If this is not supplied only locally configured
groups will be enabled.
**Support for okta auth without api_token is deprecated in Vault 1.4**
- `base_url` `(string: "")` - If set, will be used as the base domain
for API requests. If unset, "okta.com" will be used. Other valid examples
are oktapreview.com, and okta-emea.com.
- `bypass_okta_mfa` `(bool: false)` - Whether to bypass an Okta MFA request.
Useful if using one of Vault's built-in MFA mechanisms, but this will also
cause certain other statuses to be ignored, such as `PASSWORD_EXPIRED`.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"org_name": "example",
"api_token": "abc123"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/okta/config
```
## Read configuration
Reads the Okta configuration.
| Method | Path |
| :----- | :------------------ |
| `GET` | `/auth/okta/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/okta/config
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"base_url": "okta.com",
"bypass_okta_mfa": false,
"org_name": "example",
"token_bound_cidrs": [],
"token_explicit_max_ttl": 0,
"token_max_ttl": 0,
"token_no_default_policy": false,
"token_num_uses": 0,
"token_period": 0,
"token_policies": [],
"token_ttl": 0,
"token_type": "default"
},
"warnings": null
}
```
## List users
List the users configured in the Okta method.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/auth/okta/users` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/okta/users
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["fred", "jane"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Register user
Registers a new user and maps a set of policies to it.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/okta/users/:username` |
### Parameters
- `username` `(string: <required>)` - Name of the user.
- `groups` `(array: [])` - List or comma-separated string of groups associated with the user.
- `policies` `(array: [])` - List or comma-separated string of policies associated with the user.
```json
{
"policies": ["dev", "prod"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/okta/users/fred
```
## Read user
Reads the properties of an existing username.
| Method | Path |
| :----- | :--------------------------- |
| `GET` | `/auth/okta/users/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/okta/users/test-user
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"policies": ["default", "dev"],
"groups": []
},
"warnings": null
}
```
## Delete user
Deletes an existing username from the method.
| Method | Path |
| :------- | :--------------------------- |
| `DELETE` | `/auth/okta/users/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/okta/users/test-user
```
## List groups
List the groups configured in the Okta method.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `/auth/okta/groups` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/okta/groups
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["admins", "dev-users"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Register group
Registers a new group and maps a set of policies to it.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/okta/groups/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the group.
- `policies` `(array: [])` - The list or comma-separated string of policies associated with the group.
```json
{
"policies": ["dev", "prod"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/okta/groups/admins
```
## Read group
Reads the properties of an existing group.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/okta/groups/:name` |
### Parameters
- `name` `(string: <required>)` - The name for the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/okta/groups/admins
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"policies": ["default", "admin"]
},
"warnings": null
}
```
## Delete group
Deletes an existing group from the method.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/auth/okta/groups/:name` |
### Parameters
- `name` `(string: <required>)` - The name for the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/okta/users/test-user
```
## Login
Login with the username and password.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/okta/login/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `password` `(string: <required>)` - Password for the authenticating user.
- `totp` `(string: <optional>)` - Okta Verify TOTP passcode.
- `provider` `(string: <optional>)` - MFA TOTP factor provider. `GOOGLE` and `OKTA` are currently supported.
- `nonce` `(string: <optional>)` - Nonce provided during a login request to
retrieve the number verification challenge for the matching request.
### Sample payload
```json
{
"password": "Password!"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/okta/login/fred
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "fred",
"policies": "default"
},
"lease_duration": 7200,
"renewable": true
}
}
```
## Verify
Verify a number challenge that may result from an Okta Verify Push challenge.
| Method | Path |
| :----- | :--------------------------- |
| `GET` | `/auth/okta/verify/:nonce` |
### Parameters
- `nonce` `(string: <required>)` - Nonce provided if performing login that
requires number verification challenge. Logins through the vault login CLI
command will automatically generate a nonce.
### Sample request
```shell-session
$ curl \
http://127.0.0.1:8200/v1/auth/okta/verify/nonce/BCR66Ru6oJKPtC00PxJJ
```
### Sample response
```json
{
"request_id": "de6a8029-79e5-1dd1-dbe9-6405166b3f94",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"correct_answer": 94
},
"warnings": null
}
```

236
website/content/api-docs/auth/radius.mdx
View file

@ -1,236 +0,0 @@
---
layout: api
page_title: RADIUS - Auth Methods - HTTP API
description: This is the API documentation for the Vault RADIUS auth method.
---
> [!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.
# RADIUS auth method (API)
This is the API documentation for the Vault RADIUS auth method. For
general information about the usage and operation of the RADIUS method, please
see the [Vault RADIUS method documentation](/vault/docs/auth/radius).
This documentation assumes the RADIUS method is mounted at the `/auth/radius`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Configure RADIUS
Configures the connection parameters and shared secret used to communicate with
RADIUS.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/auth/radius/config` |
### Parameters
- `host` `(string: <required>)` - The RADIUS server to connect to. Examples:
`radius.myorg.com`, `127.0.0.1`
- `port` `(integer: 1812)` - The UDP port where the RADIUS server is listening
on. Defaults is 1812.
- `secret` `(string: <required>)` - The RADIUS shared secret.
- `unregistered_user_policies` `(string: "")` - A comma-separated list of
policies to be granted to unregistered users.
- `dial_timeout` `(integer: 10)` - Number of second to wait for a backend
connection before timing out. Default is 10.
- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request.
Defaults is 10.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"host": "radius.myorg.com",
"port": 1812,
"secret": "mySecret"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/radius/config
```
## Register user
Registers a new user and maps a set of policies to it. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/radius/users/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `policies` `(string: "")` - Comma-separated list of policies. If set to
empty string, only the `default` policy will be applicable to the user.
```json
{
"policies": "dev,prod"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/radius/users/test-user
```
## Read user
Reads the properties of an existing username.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/auth/radius/users/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/radius/users/test-user
```
### Sample response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"policies": "default,dev"
},
"warnings": null
}
```
## Delete user
Deletes an existing username from the method.
| Method | Path |
| :------- | :----------------------------- |
| `DELETE` | `/auth/radius/users/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/radius/users/test-user
```
## List users
List the users registered with the method.
| Method | Path |
| :----- | :------------------- |
| `LIST` | `/auth/radius/users` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/radius/users
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["devuser", "produser"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Login
Login with the username and password.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/radius/login` |
| `POST` | `/auth/radius/login/:username` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `password` `(string: <required>)` - Password for the authenticating user.
### Sample payload
```json
{
"password": "Password!"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/radius/login/test-user
```
### Sample response
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "vishal"
},
},
"lease_duration": 7200,
"renewable": true
}
```

458
website/content/api-docs/auth/saml.mdx
View file

@ -1,458 +0,0 @@
---
layout: api
page_title: SAML - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault SAML auth method.
---
> [!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.
# SAML auth method (API)
<EnterpriseAlert />
This is the API documentation for the Vault SAML auth method. To learn more about the
usage and operation, see the [Vault SAML auth method documentation](/vault/docs/auth/saml).
This documentation assumes the SAML auth method is mounted at the `/auth/saml` path in
Vault. Since it is possible to enable auth methods at any location, please update your
API calls accordingly.
## Create or update configuration
Configures the auth method with a SAML identity provider.
| Method | Path |
|:-----------| :------------------ |
| `POST/PUT` | `/auth/saml/config` |
### Parameters
- `idp_metadata_url` `(string, <required>)` - The metadata URL of the identity provider.
Mutually exclusive with `idp_sso_url`, `idp_issuer` and `idp_cert`. Must be a
well-formatted URL.
- `idp_sso_url` `(string, <required if idp_metadata_url is not set>)` - The SSO URL of the
identity provider. Mutually exclusive with `idp_metadata_url`. Must be a
well-formatted URL.
- `idp_entity_id` `(string, <required if idp_metadata_url is not set>)` - The entity ID of
the identity provider. Mutually exclusive with `idp_metadata_url`.
- `idp_cert` `(string, <required if idp_metadata_url is not set>)` - The PEM-encoded
certificate of the identity provider used to verify response and assertion signatures.
Mutually exclusive with `idp_metadata_url`.
- `entity_id` `(string, <required>)` - The entity ID of the SAML authentication
service provider. Must match entity ID configured for the application in the
SAML identity provider.
- `acs_urls` `(list, <required>)` - The well-formated URLs of your Assertion
Consumer Service (ACS) that should receive a response from the identity
provider. Vault returns a security warning if any of the given URLs lack TLS
protection.
- `default_role` `(string, <optional>)` - The role to use if no role is provided during login.
If not set, a role is required during login.
- `verbose_logging` `(bool, false)` - **Not recommended for production**. Log
additional, **potentially sensitive** information during the SAML exchange
according to the current logging level. When `verbose_logging` is `true`,
debug-level logs provide user attributes and trace-level logs provide the full
SAML response.
- `validate_response_signature` `(bool, false)` - Enables validation of signature
for at least response in the SAML response. If your IDP allows signing both response
and assertion, then recommendation is to opt in for validating signatures of both
by enabling both options.
- `validate_assertion_signature` `(bool, false)` - Enables validation of signature
for at least assertion in the SAML response. If your IDP allows signing both response
and assertion, then recommendation is to opt in for validating signatures of both
by enabling both options.
### Sample payload
```json
{
"acs_urls": "https://my.vault/v1/auth/saml/callback",
"default_role": "admin",
"entity_id": "https://my.vault/v1/auth/saml",
"idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request PUT \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/config
```
## Read configuration
Reads the auth method configuration.
| Method | Path |
| :------ | :------------------ |
| `GET` | `/auth/saml/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/config
```
### Sample response
```json
{
"request_id": "09c907d2-2dbe-8a5c-ca97-fad83195738b",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"acs_urls": [
"https://my.vault/v1/auth/saml/callback"
],
"default_role": "admin",
"entity_id": "https://my.vault/v1/auth/saml",
"idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata"
"validate_assertion_signature" : false,
"validate_response_signature" : false
},
"warnings": null
}
```
## Create or update role
Configures a role in the auth method. Roles define specific constraints required for
authentication and properties of resulting Vault tokens.
| Method | Path |
|:-----------|:-------------------------|
| `POST/PUT` | `/auth/saml/role/:name` |
### Parameters
- `name` `(string: <required>)` - URL parameter that provides the name of the role to create.
- `bound_subjects` `(string: <optional>)` - The subject being asserted for SAML
authentication. One of the provided values must match the subject returned in
the SAML assertion from the identity provider.
- `bound_subjects_type` `(string: <optional>)` - The type of matching assertion to perform
on `bound_subjects`. If `string`, requires a direct string match. If `glob`, allows for
wildcard matching using the `*` character.
- `bound_attributes` `(map: <optional>)` - Mapping of attribute names to values that are
expected to exist in the SAML assertion. The expected value may be a single string or a
comma-separated list of strings. The user will be authenticated if the SAML attributes
match at least one of the expected values.
- `bound_attributes_type` `(string: "string")` - The type of matching assertion to perform
on the key-value pairs provided by `bound_attributes`. If set to `string`, a direct string
match is required. If set to `glob`, allows for wildcard matching using the `*` character.
- `groups_attribute` `(string: <optional>)` - The attribute to use to identify the set of
groups to which the user belongs. This will be used as the names for the Identity group
aliases created due to a successful login.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"bound_attributes": "group=admin",
"bound_subjects": "*@hashicorp.com",
"bound_subjects_type": "glob",
"token_policies": "writer",
"ttl": "1h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request PUT \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/role/admin
```
## Read role
Reads a configured role.
| Method | Path |
| :----- |:------------------------|
| `GET` | `/auth/saml/role/:name` |
### Parameters
- `name` `(string: <required>)` - URL parameter that provides the name of the
role to read.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/auth/saml/role/admin
```
### Sample response
```json
{
"request_id": "3148ca9a-286e-a0a4-5a4b-31b6abb63d37",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"bound_attributes": {
"group": [
"admin"
]
},
"bound_attributes_type": "string",
"bound_subjects": [
"*@hashicorp.com"
],
"bound_subjects_type": "glob",
"groups_attribute": "",
"token_bound_cidrs": [],
"token_explicit_max_ttl": 0,
"token_max_ttl": 0,
"token_no_default_policy": false,
"token_num_uses": 0,
"token_period": 0,
"token_policies": [
"writer"
],
"token_ttl": 0,
"token_type": "default"
},
"warnings": null
}
```
## List roles
Lists all the configured roles.
| Method | Path |
| :----- | :---------------- |
| `LIST` | `/auth/saml/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/auth/saml/role?list=true
```
### Sample response
```json
[
"admin",
"operations"
]
```
## Delete Role
Deletes a configured role.
| Method | Path |
| :------- | :---------------------- |
| `DELETE` | `/auth/saml/role/:name` |
### Parameters
- `name` `(string: <required>)` - URL parameter that provides the name of the
role to delete.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/saml/role/admin
```
## Obtain SSO service URL
Starts a login flow by providing a SAML Single Sign-On (SSO) Service URL for the
configured identity provider. The returned `token_poll_id` can be used to obtain
the Vault token after the user is authenticated with the identity provider and the
SAML response has passed validation.
<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>
| Method | Path |
|:--------|:-----------------------------|
| `POST` | `/auth/saml/sso_service_url` |
### Parameters
- `role` `(string, <optional>)` - The role name to use for the login flow.
Defaults to the role configured with `default_role`.
- `client_challenge` `(string, <required>)` - The client challenge value. Must be the
output of a base64-encoded, sha256 digest of the `client_verifier` eventually provided
to the [Token API](/vault/api-docs/auth/saml#obtain-vault-token). Must be at least 44
bytes in length.
- `client_type` `(string, <required>)` - The type of the requesting client. The response
from the Assertion Consumer Service [Callback API](/vault/api-docs/auth/saml#assertion-consumer-service-callback)
will differ based on the provided type. If `cli`, an HTML success page will be returned
in the response. If `browser`, a blank HTML page will be returned in the response.
- `acs_url` `(string, <required>)` - The URL where the identity provider will send its
SAML response. Must be in the set of configured [`acs_urls`](/vault/api-docs/auth/saml#acs_urls).
### Sample payload
```json
{
"acs_url": "https://my.vault/v1/auth/saml/callback",
"client_challenge": "Z6+7owP80d1aHTha1kdixtT99JkvmG4TPSgbvDwZ70A=",
"client_type": "cli",
"role": "admin"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/sso_service_url
```
### Sample response
```json
{
"sso_service_url": "https://example.okta.com/app/abc123eb9xnIfzlaf697/id/sso/saml?RelayState=...&SAMLRequest=...",
"token_poll_id": "ee442348-159b-df10-4c59-63050069df4d"
}
```
## Assertion consumer service callback
The assertion consumer service URL of the auth method. Completes the round trip from
the identity provider and performs validations on the SAML response.
<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>
| Method | Path |
|:--------|:----------------------|
| `POST` | `/auth/saml/callback` |
### Parameters
- `RelayState` `(string, <required>)` - The relay state from the original SAML
authentication request that was returned by the identity provider.
- `SAMLResponse` `(string, <required>)` - The signed SAML response from the identity
provider.
### Sample payload
```json
{
"RelayState": "0afe62a9-7b83-a182-0650-c749badfb900",
"SAMLResponse": "..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/callback
```
## Obtain vault token
The token endpoint completes the login flow by returning a Vault token.
<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>
| Method | Path |
|:--------|:-------------------|
| `POST` | `/auth/saml/token` |
### Parameters
- `client_verifier` `(string, <required>)` - The value which produced the `client_challenge`
provided to the [SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url)
at the start of the authentication flow. Its base64-encoded, sha256 digest must match the
`client_challenge` value.
- `token_poll_id` `(string, <required>)` - The `token_poll_id` value returned from the
[SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url) at the start of
the authentication flow.
### Sample payload
```json
{
"client_verifier": "59634224-5869-6002-e0b1-35370b8f6b82",
"token_poll_id": "ee442348-159b-df10-4c59-63050069df4d"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/saml/token
```
### Sample response
```json
{
"request_id": "b16f7cf9-0970-2e64-69d6-f00d055e93c4",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": null,
"warnings": null,
"auth": {
"client_token": "hvs.CAES...",
"accessor": "Rl4gU4amxzBFpFBJixv8xJBK",
"policies": [
"default",
"writer"
],
"token_policies": [
"default",
"writer"
],
"identity_policies": null,
"metadata": {
"role": "admin"
},
"orphan": true,
"entity_id": "afd74442-6c48-3d2f-9449-689ce050ba88",
"lease_duration": 3600,
"renewable": true,
"mfa_requirement": null
}
}
```

209
website/content/api-docs/auth/scep.mdx
View file

@ -1,209 +0,0 @@
---
layout: api
page_title: SCEP - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault SCEP authentication
method.
---
> [!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.
# SCEP auth method (API)
Use the SCEP authentication plugin API to interact with a mounted plugin
instance. For general information about the usage and operation of the
SCEP method, refer to the [Vault SCEP method documentation](/vault/docs/auth/scep).
## Create SCEP role
Creates or updates a named SCEP role.
| Method | Path |
|:-------|:------------------------|
| `POST` | `/auth/{mount_path}/role/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the SCEP role.
- `display_name` `(string: "<name>")` - The `display_name` value for tokens
issued when authenticating against the role. Defaults to `name`.
- `auth_type` `(enum: <required>)` - Required authentication type for the SCEP
role. Must be one of: `static-challenge`, `intune`.
- `challenge` `(string: "")` - The authentication challenge to use when
`auth_type` is `static-challenge`.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"auth_type": "static-challenge",
"challenge": "super-secret-challenge",
"display_name": "test",
"token_policies": ["access-scep"],
"token_type": "batch"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1
```
### Sample response
```json
{
"request_id": "c22d68ec-ac3d-ea24-d5d0-efe07dcc0ef6",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"auth_type": "static-challenge",
"display_name": "test",
"name": "static-challenge-1",
"token_bound_cidrs": [],
"token_explicit_max_ttl": 0,
"token_max_ttl": 0,
"token_no_default_policy": false,
"token_num_uses": 0,
"token_period": 0,
"token_policies": [
"access-scep"
],
"token_ttl": 0,
"token_type": "batch"
},
"wrap_info": null,
"warnings": null,
"auth": null,
"mount_type": "scep"
}
```
## Read SCEP role
Get information associated with the named role.
| Method | Path |
|:-------|:------------------------|
| `GET` | `/auth/{mount_path}/role/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the SCEP role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1
```
### Sample response
```json
{
"request_id": "07c9bfcc-ee30-6ba9-fce8-07bae5033989",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"auth_type": "static-challenge",
"display_name": "static-challenge-1",
"name": "static-challenge-1",
"token_bound_cidrs": [],
"token_explicit_max_ttl": 0,
"token_max_ttl": 0,
"token_no_default_policy": false,
"token_num_uses": 0,
"token_period": 0,
"token_policies": [
"access-scep"
],
"token_ttl": 0,
"token_type": "batch"
},
"wrap_info": null,
"warnings": null,
"auth": null,
"mount_type": "scep"
}
```
## List SCEP roles
List all currently configured SCEP role names.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/auth/{mount_path}/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/scep/role
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["static-challenge-1", "intune-1"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete SCEP role
Delete the named role.
| Method | Path |
|:---------|:------------------------|
| `DELETE` | `/auth/{mount_path}/role/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the SCEP role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1
```
## Login
SCEP authentication endpoint for delegated authentication from a PKI mount.
| Method | Path |
|:-------|:-------------------|
| `POST` | `/auth/{mount_path}/login` |
### Parameters
- `name` `(string: "")` - The SCEP role associated with the PKI mount. Leaving
`name` unset tells Vault to try all SCEP roles and return the first one that
matches.

854
website/content/api-docs/auth/token.mdx
View file

@ -1,854 +0,0 @@
---
layout: api
page_title: Token - Auth Methods - HTTP API
description: This is the API documentation for the Vault token auth method.
---
> [!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.
# Token auth method (API)
This is the API documentation for the Vault token auth method. For
general information about the usage and operation of the token method, please
see the [Vault Token method documentation](/vault/docs/auth/token).
## List accessors
This endpoint lists token accessor. This requires `sudo` capability, and access
to it should be tightly controlled as the accessors can be used to revoke very
large numbers of tokens and their associated leases at once.
| Method | Path |
| :----- | :---------------------- |
| `LIST` | `/auth/token/accessors` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/token/accessors
```
### Sample response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"476ea048-ded5-4d07-eeea-938c6b4e43ec",
"bb00c093-b7d3-b0e9-69cc-c4d85081165b"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create token
Creates a new token. Certain options are only available when called by a
root token. If used via the `/auth/token/create-orphan` endpoint, a root
token is not required to create an orphan token (otherwise set with the
`no_parent` option). If used with a role name in the path, the token will
be created against the specified role name; this may override options set
during this call.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/auth/token/create` |
| `POST` | `/auth/token/create-orphan` |
| `POST` | `/auth/token/create/:role_name` |
### Parameters
- `id` `(string: "")` – The ID of the client token. Can only be specified by a
root token. The ID provided may not contain a `.` character. Otherwise, the
token ID is a randomly generated value.
_Note:_ The ID should not start with the `s.` prefix.
- `role_name` `(string: "")` – The name of the token role.
- `policies` `(array: "")` – A list of policies for the token. This must be a
subset of the policies belonging to the token making the request, unless
the calling token is root or contains `sudo` capabilities to `auth/token/create`.
If not specified, defaults to all the policies of the calling token.
- `meta` `(map: {})` – A map of string to string valued metadata. This is
passed through to the audit devices.
- `no_parent` `(bool: false)` - This argument only has effect if used by a root
or sudo caller. When set to true, the token created will not have a parent.
- `no_default_policy` `(bool: false)` - If true the `default` policy will not be
contained in this token's policy set.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `lease` `(string: "")` - DEPRECATED; use `ttl` instead
- `ttl` `(string: "")` - The TTL period of the token, provided as "1h", where
hour is the largest suffix. If not provided, the token is valid for the
[default lease TTL](/vault/docs/configuration), or indefinitely if the
root policy is used.
- `type` `(string: "")` - The token type. Can be "batch" or "service". Defaults
to the type specified by the role configuration named by `role_name`.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL _cannot_ be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `display_name` `(string: "token")` - The display name of the token.
- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be
used to create a one-time-token or limited use token. The value of 0 has no
limit to the number of uses.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
will use the given period. Requires a root token or one with the sudo capability.
- `entity_alias` `(string: "")` - Name of the entity alias to associate with
during token creation. Only works in combination with `role_name` argument
and used entity alias must be listed in `allowed_entity_aliases`. If this has
been specified, the entity will not be inherited from the parent.
### Sample payload
```json
{
"policies": ["web", "stage"],
"meta": {
"user": "armon"
},
"ttl": "1h",
"renewable": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/create
```
### Sample response
```json
{
"request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": [
"Policy \"stage\" does not exist",
"Policy \"web\" does not exist"
],
"auth": {
"client_token": "s.wOrq9dO9kzOcuvB06CMviJhZ",
"accessor": "B6oixijqmeR4bsLOJH88Ska9",
"policies": ["default", "stage", "web"],
"token_policies": ["default", "stage", "web"],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true,
"entity_id": "",
"token_type": "service",
"orphan": false,
"num_uses": 0
}
}
```
## Lookup a token
Returns information about the client token.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/auth/token/lookup` |
### Parameters
- `token` `(string: <required>)` - Token to lookup.
### Sample payload
```json
{
"token": "ClientToken"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/lookup
```
### Sample response
```json
{
"data": {
"accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
"creation_time": 1523979354,
"creation_ttl": 2764800,
"display_name": "ldap2-tesla",
"entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
"expire_time": "2018-05-19T11:35:54.466476215-04:00",
"explicit_max_ttl": 0,
"id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
"identity_policies": ["dev-group-policy"],
"issue_time": "2018-04-17T11:35:54.466476078-04:00",
"meta": {
"username": "tesla"
},
"num_uses": 0,
"orphan": true,
"path": "auth/ldap2/login/tesla",
"policies": ["default", "testgroup2-policy"],
"renewable": true,
"ttl": 2764790
}
}
```
## Lookup a token (Self)
Returns information about the current client token.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/token/lookup-self` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/token/lookup-self
```
### Sample response
```json
{
"data": {
"accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
"creation_time": 1523979354,
"creation_ttl": 2764800,
"display_name": "ldap2-tesla",
"entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
"expire_time": "2018-05-19T11:35:54.466476215-04:00",
"explicit_max_ttl": 0,
"id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
"identity_policies": ["dev-group-policy"],
"issue_time": "2018-04-17T11:35:54.466476078-04:00",
"meta": {
"username": "tesla"
},
"num_uses": 0,
"orphan": true,
"path": "auth/ldap2/login/tesla",
"policies": ["default", "testgroup2-policy"],
"renewable": true,
"ttl": 2764790
}
}
```
## Lookup a token (Accessor)
Returns information about the client token from the accessor.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/auth/token/lookup-accessor` |
### Parameters
- `accessor` `(string: <required>)` - Token accessor to lookup.
### Sample payload
```json
{
"accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/lookup-accessor
```
### Sample response
```json
{
"data": {
"accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
"creation_time": 1523979354,
"creation_ttl": 2764800,
"display_name": "ldap2-tesla",
"entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
"expire_time": "2018-05-19T11:35:54.466476215-04:00",
"explicit_max_ttl": 0,
"id": "",
"identity_policies": ["dev-group-policy"],
"issue_time": "2018-04-17T11:35:54.466476078-04:00",
"meta": {
"username": "tesla"
},
"num_uses": 0,
"orphan": true,
"path": "auth/ldap2/login/tesla",
"policies": ["default", "testgroup2-policy"],
"renewable": true,
"ttl": 2763902
}
}
```
## Renew a token
Renews a lease associated with a token. This is used to prevent the expiration
of a token, and the automatic revocation of it. Token renewal is possible only
if there is a lease associated with it.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/auth/token/renew` |
### Parameters
- `token` `(string: <required>)` - Token to renew. This can be part of the URL
or the body.
- `increment` `(string: "")` - An optional requested increment duration can be
provided. This increment may not be honored, for instance in the case of periodic tokens.
If not supplied, Vault will use the default TTL. This is specified as a numeric string
with suffix like "30s" or "5m".
### Sample payload
```json
{
"token": "ClientToken"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/renew
```
### Sample response
```json
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true
}
}
```
## Renew a token (Self)
Renews a lease associated with the calling token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token renewal is
possible only if there is a lease associated with it.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/auth/token/renew-self` |
### Parameters
- `increment` `(string: "")` - An optional requested increment duration can be
provided. This increment may not be honored, for instance in the case of periodic tokens.
If not supplied, Vault will use the default TTL. This is specified as a numeric string
with suffix like "30s" or "5m".
### Sample payload
```json
{
"increment": "1h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/renew-self
```
### Sample response
```json
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true
}
}
```
## Renew a token (Accessor)
Renews a lease associated with a token using its accessor. This is used to
prevent the expiration of a token, and the automatic revocation of it. Token
renewal is possible only if there is a lease associated with it.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/auth/token/renew-accessor` |
### Parameters
- `accessor` `(string: <required>)` - Accessor associated with the token to
renew.
- `increment` `(string: "")` - An optional requested lease increment can be
provided. This increment may be ignored.
### Sample payload
```json
{
"accessor": "7JFKXuXKXa2D44YfDiovZ9aq"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/renew-accessor
```
### Sample response
```json
{
"auth": {
"client_token": "",
"policies": ["web", "stage"],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true
}
}
```
## Revoke a token
Revokes a token and all child tokens. When the token is revoked, all dynamic secrets
generated with it are also revoked.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/auth/token/revoke` |
### Parameters
- `token` `(string: <required>)` - Token to revoke.
### Sample payload
```json
{
"token": "ClientToken"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/revoke
```
## Revoke a token (Self)
Revokes the token used to call it and all child tokens. When the token is
revoked, all dynamic secrets generated with it are also revoked.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/token/revoke-self` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/token/revoke-self
```
## Revoke a token accessor
Revoke the token associated with the accessor and all the child tokens. This is
meant for purposes where there is no access to token ID but there is need to
revoke a token and its children.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/auth/token/revoke-accessor` |
### Parameters
- `accessor` `(string: <required>)` - Accessor of the token.
### Sample payload
```json
{
"accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/revoke-accessor
```
## Revoke token and orphan children
Revokes a token but not its child tokens. When the token is revoked, all secrets
generated with it are also revoked. All child tokens are orphaned, but can be
revoked sub-sequently using `/auth/token/revoke/`. This is a root-protected
endpoint.
| Method | Path |
| :----- | :-------------------------- |
| `POST` | `/auth/token/revoke-orphan` |
### Parameters
- `token` `(string: <required>)` - Token to revoke. This can be part of the URL
or the body.
### Sample payload
```json
{
"token": "ClientToken"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/revoke-orphan
```
## Read token role
Fetches the named role configuration.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/auth/token/roles/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - The name of the token role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/token/roles/nomad
```
### Sample response
```javascript
{
"request_id": "075a19cd-4e56-a3ca-d956-7609819831ec",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"allowed_entity_aliases": [
"my-entity-alias"
],
"allowed_policies": [],
"disallowed_policies": [],
"allowed_policies_glob": [],
"disallowed_policies_glob": [],
"explicit_max_ttl": 0,
"name": "nomad",
"orphan": false,
"path_suffix": "",
"period": 0,
"renewable": true,
"token_explicit_max_ttl": 0,
"token_no_default_policy": false,
"token_period": 0,
"token_type": "default-service"
},
"warnings": null
}
```
## List token roles
List available token roles.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `/auth/token/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
http://127.0.0.1:8200/v1/auth/token/roles
```
### Sample response
```json
{
"data": {
"keys": ["role1", "role2"]
}
}
```
## Create/Update token role
Creates (or replaces) the named role. Roles enforce specific behavior when
creating tokens that allow token functionality that is otherwise not
available or would require `sudo`/root privileges to access. Role
parameters, when set, override any provided options to the `create`
endpoints. The role name is also included in the token path, allowing all
tokens created against a role to be revoked using the
`/sys/leases/revoke-prefix` endpoint.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/token/roles/:role_name` |
### Parameters
- `role_name` `(string: <required>)` – The name of the token role.
- `allowed_policies` `(list: [])` – If set, tokens can be created with any
subset of the policies in this list, rather than the normal semantics of
tokens being a subset of the calling token's policies. The parameter is a
comma-delimited string of policy names. If at creation time
`no_default_policy` is not set and `"default"` is not contained in
`disallowed_policies` or glob matched in `disallowed_policies_glob`,
the `"default"` policy will be added to the created token automatically.
- `disallowed_policies` `(list: [])` – If set, successful token creation via
this role will require that no policies in the given list are requested. The
parameter is a comma-delimited string of policy names. Adding `"default"` to
this list will prevent `"default"` from being added automatically to created
tokens.
- `allowed_policies_glob` `(list: [])` – If set, tokens can be created with any
subset of glob matched policies in this list, rather than the normal semantics
of tokens being a subset of the calling token's policies. The parameter is a
comma-delimited string of policy name globs. If at creation time
`no_default_policy` is not set and `"default"` is not contained in
`disallowed_policies` or glob matched in `disallowed_policies_glob`,
the `"default"` policy will be added to the created token automatically.
If combined with `allowed_policies` policies need to only match one of the two
lists to be permitted. Note that unlike `allowed_policies` the policies listed
in `allowed_policies_glob` will not be added to the token when no policies are
specified in the call to `/auth/token/create/:role_name`.
- `disallowed_policies_glob` `(list: [])` – If set, successful token creation via
this role will require that no requested policies glob match any of policies in
this list. The parameter is a comma-delimited string of policy name globs.
Adding any glob that matches `"default"` to this list will prevent `"default"`
from being added automatically to created tokens.
If combined with `disallowed_policies` policies need to only match one of the
two lists to be blocked.
- `orphan` `(bool: false)` - If `true`, tokens created against this policy will
be orphan tokens (they will have no parent). As such, they will not be
automatically revoked by the revocation of any other token.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `path_suffix` `(string: "")` - If set, tokens created against this role will
have the given suffix as part of their path in addition to the role name. This
can be useful in certain scenarios, such as keeping the same role name in the
future but revoking all tokens created against it before some point in time.
The suffix can be changed, allowing new callers to have the new suffix as part
of their path, and then tokens with the old suffix can be revoked via
`/sys/leases/revoke-prefix`.
- `allowed_entity_aliases` `(string: "", or list: [])` - String or JSON list
of allowed entity aliases. If set, specifies the entity aliases which are
allowed to be used during token generation. This field supports globbing.
Note that `allowed_entity_aliases` is not case sensitive.
@include 'tokenstorefields.mdx'
### Sample payload
```json
"allowed_policies": [
"dev"
],
"name": "nomad",
"orphan": false,
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
"renewable": true,
"allowed_entity_aliases": ["web-entity-alias", "app-entity-*"]
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST
--data @payload.json
http://127.0.0.1:8200/v1/auth/token/roles/nomad
```
## Delete token role
This endpoint deletes the named token role.
| Method | Path |
| :------- | :----------------------------- |
| `DELETE` | `/auth/token/roles/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - The name of the token role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/token/roles/admins
```
## Tidy tokens
Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. On Enterprise, Tidy will only impact the tokens in the
specified namespace, or the root namespace if unspecified.
Generally, running this is not needed unless upgrade notes or support personnel
suggest it. There are two potential dangers to running tidy: first, this will
perform a lot of read I/O to the storage method, as it will essentially reload the
entirety of the token store into memory. Depending on how much cleanup is
required (usually very little) there may also be a large number of writes.
Second, this will cause Vault's memory usage to balloon up, because the default
Vault internal cache is unlimited in size and every value read from storage will
be cached. Listing the `/auth/token/accessors` endpoint is a good way to get
some sense of the potential impact: tidy does this and more, so if this call creates problems
for your cluster, it would be wise to give Vault more resources before attempting
tidy. Note that the request may time out depending on
[max duration](/vault/docs/configuration#default_max_request_duration)
and your client's timeout configuration, make sure to allow it run to completion
to properly judge the impact.
Tidy will load every token accessor and cubbyhole in the namespace, as well
as all the secondary index entries that are used to group tokens into trees so
that parent token revocation also revokes child tokens.
For each parent token listed in the secondary index, tidy will check if the token
still exists in storage, and if not its child tokens that still exist will be
made orphans, then the parent token will be removed from the secondary index.
For each accessor found, tidy will check if the corresponding token still exists
in storage, and if not will delete the accessor. If the token still exists in
storage but shouldn't, tidy will try to revoke it and any child leases it might
have, then delete the accessor.
Finally, any cubbyhole entries that are associated with tokens which weren't deemed
valid in the above steps will be deleted.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/token/tidy` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/token/tidy
```
### Sample response
```json
{
"request_id": "84437c7f-36a1-6c1d-381d-14ec99217e94",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": [
"Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs."
],
"auth": null
}
```

297
website/content/api-docs/auth/userpass.mdx
View file

@ -1,297 +0,0 @@
---
layout: api
page_title: Userpass - Auth Methods - HTTP API
description: |-
This is the API documentation for the Vault username and password
auth method.
---
> [!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.
# Userpass auth method (HTTP API)
This is the API documentation for the Vault Username & Password auth method. For
general information about the usage and operation of the Username and Password method, please
see the [Vault Userpass method documentation](/vault/docs/auth/userpass).
This documentation assumes the Username & Password method is mounted at the `/auth/userpass`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Create/Update user
Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path |
| :----- | :------------------------------- |
| `POST` | `/auth/userpass/users/:username` |
### Parameters
- `username` `(string: <required>)` – The username for the user. Accepted characters: alphanumeric plus "_", "-", "." (underscore, hyphen and period); username cannot begin with a hyphen, nor can it begin or end with a period.
- `password` `(string: <required if password_hash is not given>)` - Password for the current user. Only required when creating the user. Mutually exclusive with `password_hash`.
- `password_hash` `(string: <required if password is not given>)` - Pre-hashed password for the current user in bcrypt format. Mutually exclusive with `password`.
@include 'tokenfields.mdx'
### Sample payload
```json
{
"password": "superSecretPassword",
"token_policies": ["admin", "default"],
"token_bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```
### Examples
Set role-level TTL values for a user named "alice" so the generated lease has a
default TTL of 8 hours (28800 seconds) and maximum TTL of 12 hours
(43200 seconds):
```shell-session
$ curl \
--header "X-Vault-Token: $VAULT_TOKEN" \
--request POST \
--data '{"token_ttl":"8h","token_max_ttl":"12h"}' \
$VAULT_ADDR/v1/auth/userpass/users/alice
```
## Read user
Reads the properties of an existing username.
| Method | Path |
| :----- | :------------------------------- |
| `GET` | `/auth/userpass/users/:username` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```
### Sample response
```json
{
"request_id": "0ad1be52-9398-4b3c-f58b-98e427406471",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"token_bound_cidrs": [
"127.0.0.1",
"128.252.0.0/16"
],
"token_explicit_max_ttl": 0,
"token_max_ttl": 0,
"token_no_default_policy": false,
"token_num_uses": 0,
"token_period": 0,
"token_policies": [
"admin",
"default"
],
"token_ttl": 0,
"token_type": "default"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Delete user
This endpoint deletes the user from the method.
| Method | Path |
| :------- | :------------------------------- |
| `DELETE` | `/auth/userpass/users/:username` |
### Parameters
- `username` `(string: <required>)` - The username for the user.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```
## Update password on user
Update password for an existing user.
| Method | Path |
| :----- | :---------------------------------------- |
| `POST` | `/auth/userpass/users/:username/password` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user.
### Sample payload
```json
{
"password": "superSecretPassword2"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/password
```
## Update policies on user
Update policies for an existing user.
| Method | Path |
| :----- | :---------------------------------------- |
| `POST` | `/auth/userpass/users/:username/policies` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `token_policies` `(array: [] or comma-delimited string: "")` - List of
policies to encode onto generated tokens. Depending on the auth method, this
list may be supplemented by user/group/other values.
### Sample payload
```json
{
"token_policies": ["policy1", "policy2"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/policies
```
## List users
List available userpass users.
| Method | Path |
| :----- | :--------------------- |
| `LIST` | `/auth/userpass/users` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/userpass/users
```
### Sample response
```json
{
"data": {
"keys": ["mitchellh", "armon"]
}
}
```
## Login
Login with the username and password.
| Method | Path |
| :----- | :------------------------------- |
| `POST` | `/auth/userpass/login/:username` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user.
### Sample payload
```json
{
"password": "superSecretPassword2"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
```
### Sample response
```json
{
"request_id": "ae1882ba-f60a-7629-ce1a-6618c482de3e",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": null,
"auth": {
"client_token": "hvs.CAESIJyeFmhLYRWVXPJStT3fDP1ZdFkon_otuk1sJUpkfk_WGh4KHGh2cy5xdW9XVHBnVUwwbzB1ZEhzZkpkRmVoU08",
"accessor": "iP2Lw1JXpjlALbgJSeIx51n7",
"policies": [
"default",
"policy1",
"policy2"
],
"token_policies": [
"default",
"policy1",
"policy2"
],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 2764800,
"renewable": true,
"entity_id": "0660dce5-4f2c-926a-8b15-158901557d9d",
"token_type": "service",
"orphan": true,
"mfa_requirement": null,
"num_uses": 0
}
}
```

346
website/content/api-docs/index.mdx
View file

@ -1,346 +0,0 @@
---
layout: api
page_title: HTTP API
description: Vault has an HTTP API that can be used to control every aspect of Vault.
---
> [!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.
# HTTP API
The Vault HTTP API gives you full access to Vault using [REST like HTTP verbs](https://en.wikipedia.org/wiki/Representational_state_transfer).
Every aspect of Vault can be controlled using the APIs. The Vault CLI uses the
HTTP API to access Vault similar to all other consumers.
All API routes are prefixed with `/v1/`.
This documentation is only for the v1 API, which is currently the only version.
~> **Backwards compatibility:** At the current version, Vault does not yet
promise backwards compatibility even with the v1 prefix. We'll remove this
warning when this policy changes. At this point in time the core API (that
is, `sys/` routes) change very infrequently, but various secrets engines/auth
methods/etc. sometimes have minor changes to accommodate new features as
they're developed.
## Transport
The API is expected to be accessed over a TLS connection at all times, with a
valid certificate that is verified by a well-behaved client. It is possible to
disable TLS verification for listeners, however, so API clients should expect
to have to do both depending on user settings.
## Authentication
Once Vault is unsealed, almost every other operation requires a _client token_.
A user may have a client token sent to them. The client token must be sent as
either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using
the `Bearer <token>` scheme.
Otherwise, a client token can be retrieved using an [authentication
engine](/vault/docs/auth).
Each auth method has one or more unauthenticated login endpoints. These
endpoints can be reached without any authentication, and are used for
authentication to Vault itself. These endpoints are specific to each auth
method.
Responses from auth login methods that generate an authentication token are
sent back to the client in JSON. The resulting token should be saved on the
client or passed via the `X-Vault-Token` or `Authorization` header for future requests.
## Parameter restrictions
Several Vault APIs require specifying path parameters. The path parameter cannot end
in periods. Otherwise, Vault will return a 404 unsupported path error.
## Namespaces
@include 'alerts/enterprise-and-hcp.mdx'
When using [Namespaces](/vault/docs/enterprise/namespaces) the final path of the API
request is relative to the `X-Vault-Namespace` header. For instance, if a
request URI is `secret/foo` with the `X-Vault-Namespace` header set as `ns1/ns2/`,
then the resulting request path to Vault will be `ns1/ns2/secret/foo`.
Note that it is semantically equivalent to use the full path rather than the
`X-Vault-Namespace` header, Vault will match the corresponding namespace
based on correlating user input. Similar path results may be achieved if
`X-Vault-Namespace` is set to `ns1/` with the request path of `ns2/secret/foo`
as well, or otherwise if `X-Vault-Namespace` is omitted entirely and instead a
complete path is provided such as: `ns1/ns2/secret/foo`.
For example, the following two commands result in equivalent requests:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "X-Vault-Namespace: ns1/ns2/" \
-X GET \
http://127.0.0.1:8200/v1/secret/foo
```
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X GET \
http://127.0.0.1:8200/v1/ns1/ns2/secret/foo
```
Some APIs are only available in a limited number of namespaces. More details
are available in the Namespace
[documentation](/vault/docs/enterprise/namespaces#restricted-api-paths).
<Warning title="HCP Vault Dedicated">
When you are working with HCP Vault Dedicated, your request must specify the
target namespace. In absence of an explicit namespace, Vault tries to send
the request to `root` namespace which results in an error.
The top-level namespace for HCP Vault Dedicated clusters is `admin`, so the
requests must include `-H "X-Vault-Namespace: admin"` header or `admin` in the
API endpoint path.
</Warning>
## API operations
Typically the request data, body and response data to and from Vault is in JSON.
Vault sets the `Content-Type` header appropriately with its response and does
not require it from the clients request.
The demonstration below uses the [`KVv1` secrets engine](/vault/api-docs/secret/kv/kv-v1), which is a
simple Key Value store. Please read [the API documentation of KV secret engines](/vault/api-docs/secret/kv)
for details of `KVv1` compared to `KVv2` and how they differ in their URI paths
as well as the features available in version 2 of the KV secrets engine.
For `KVv1`, reading a secret using the HTTP API is done by issuing a GET:
```text
/v1/secret/foo
```
This maps to `secret/foo` where `foo` is the key in the `secret/` mount, which
is mounted by default on a fresh Vault install and is of type `kv`.
Here is an example of reading a secret using cURL:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X GET \
http://127.0.0.1:8200/v1/secret/foo
```
A few endpoints consume calls with `GET` query string parameters, but only if
those parameters are not sensitive, especially since some load balancers will
be able log these. Most endpoints that accept `POST` query string parameters
expect those parameters in the request body.
You can list secrets as well. To do this, either issue a `GET` with the query
string parameter `list=true`, or you use the `LIST` HTTP verb. For the `kv` secrets
engine, listing is allowed on directories only, which returns the keys at the
requested path:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X LIST \
http://127.0.0.1:8200/v1/secret/
```
The API documentation uses `LIST` as the HTTP verb, but you can still use `GET`
with the `?list=true` query string.
If the list result is an empty set, Vault responds with status code 404 and the following JSON:
```json
{"errors":[]}
```
To make an API with specific data in request body, issue a `POST`:
```text
/v1/secret/foo
```
with a JSON body like:
```javascript
{
"value": "bar"
}
```
Here is an example of writing a secret using cURL:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "Content-Type: application/json" \
-X POST \
-d '{"data":{"value":"bar"}}' \
http://127.0.0.1:8200/v1/secret/baz
```
Vault currently considers `PUT` and `POST` to be synonyms. Rather than trust a
client's stated intentions, Vault engines can implement an existence check to
discover whether an operation is actually a create or update operation based on
the data already stored within Vault. This makes permission management via ACLs
more flexible.
A [KVv2 example](/vault/api-docs/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is
appended with ***`data/`*** prior to the secret name (`baz`) such as:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "Content-Type: application/json" \
-X POST \
-d '{"data":{"value":"bar"}}' \
http://127.0.0.1:8200/v1/secret/data/baz
```
For more examples, please look at the Vault API client.
## The `X-Vault-Request` header
Requests that are sent to a [Vault Proxy][proxy] that is configured to use the
`require_request_header` option must include the `X-Vault-Request` header
entry, e.g.:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "X-Vault-Request: true" \
-H "Content-Type: application/json" \
-X POST \
-d '{"value":"bar"}' \
http://127.0.0.1:8200/v1/secret/baz
```
The Vault CLI always adds this header to every request, regardless of whether
the request is being sent to a Vault Agent or directly to a Vault Server. In
addition, the Vault SDK always adds this header to every request.
## Help
To retrieve the help for any API within Vault, including mounted engines, auth
methods, etc. then append `?help=1` to any URL. If you have valid permission to
access the path, then the help text will be returned as a markdown-formatted block
in the `help` attribute of the response.
Additionally, with the [OpenAPI generation](/vault/api-docs/system/internal-specs-openapi) in Vault, you will get back a small
OpenAPI document in the `openapi` attribute. This document is relevant for the
path you're looking up and any paths under it - also note paths in the OpenAPI
document are relative to the initial path queried.
Example request:
```shell-session
$ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
http://127.0.0.1:8200/v1/secret?help=1
```
Example response:
```javascript
{
"help": "## DESCRIPTION\n\nThis backend provides a versioned key-value store. The kv backend reads and\nwrites arbitrary secrets to the storage backend. The secrets are\nencrypted/decrypted by Vault: they are never stored unencrypted in the backend\nand the backend never has an opportunity to see the unencrypted value. Each key\ncan have a configured number of versions, and versions can be retrieved based on\ntheir version numbers.\n\n## PATHS\n\nThe following paths are supported by this backend. To view help for\nany of the paths below, use the help command with any route matching\nthe path pattern. Note that depending on the policy of your auth token,\nyou may or may not be able to access certain paths.\n\n ^.*$\n\n\n ^config$\n Configures settings for the KV store\n\n ^data/(?P<path>.*)$\n Write, Read, and Delete data in the Key-Value Store.\n\n ^delete/(?P<path>.*)$\n Marks one or more versions as deleted in the KV store.\n\n ^destroy/(?P<path>.*)$\n Permanently removes one or more versions in the KV store\n\n ^metadata/(?P<path>.*)$\n Configures settings for the KV store\n\n ^undelete/(?P<path>.*)$\n Undeletes one or more versions from the KV store.",
"openapi": {
"openapi": "3.0.2",
"info": {
"title": "HashiCorp Vault API",
"description": "HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.",
"version": "1.0.0",
"license": {
"name": "Mozilla Public License 2.0",
"url": "https://www.mozilla.org/en-US/MPL/2.0"
}
},
"paths": {
"/.*": {},
"/config": {
"description": "Configures settings for the KV store",
"x-vault-create-supported": true,
"get": {
"summary": "Read the backend level settings.",
"tags": [
"secrets"
],
"responses": {
"200": {
"description": "OK"
}
}
},
...[output truncated]...
}
}
}
```
## Error response
A common JSON structure is always returned to return errors:
```javascript
{
"errors": [
"message",
"another message"
]
}
```
This structure will be returned for any HTTP status greater than or equal to 400.
## HTTP status codes
The following HTTP status codes are used throughout the API. Vault tries to
adhere to these whenever possible, but in case it doesn't -- then feel free to
[raise a bug](https://github.com/hashicorp/vault/issues) for our attention!
~> _Note_: Applications should be prepared to accept both `200` and `204` as
success. `204` is simply an indication that there is no response body to parse,
but API endpoints that indicate that they return a `204` may return a `200` if
warnings are generated during the operation.
- `200` - Success with data.
- `204` - Success, no data returned.
- `400` - Invalid request, missing or invalid data.
- `403` - Forbidden, your authentication details are either incorrect, you
don't have access to this feature, or - if CORS is enabled - you made a
cross-origin request from an origin that is not allowed to make such
requests.
- `404` - Invalid path. This can both mean that the path truly doesn't exist or
that you don't have permission to view a specific path. We use 404 in some
cases to avoid state leakage. LIST requests with no results will also return 404s.
- `405` - Unsupported operation. You tried to use a method inappropriate to
the request path, e.g. a POST on an endpoint that only accepts GETs.
- `412` - Precondition failed. Returned on Enterprise when a request can't be
processed yet due to some missing eventually consistent data. Should be retried,
perhaps with a little backoff.
See [Vault Eventual Consistency](/vault/docs/enterprise/consistency).
- `429` - Default return code for health status of standby nodes. This will
likely change in the future.
- `472` - Default return code for disaster recovery mode replication secondary and active.
- `473` - Default return code for health status of performance standby nodes.
- `500` - Internal server error. An internal error has occurred, try again
later. If the error persists, report a bug.
- `501` - Vault is not initialized.
- `502` - A request to Vault required Vault making a request to a third party;
the third party responded with an error of some kind.
- `503` - Vault is down for maintenance or is currently sealed. Try again
later.
## Limits
A maximum request size of 32MB is imposed to prevent a denial of service attack
with arbitrarily large requests; this can be tuned per `listener` block in
Vault's server configuration file.
[proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza

226
website/content/api-docs/libraries.mdx
View file

@ -1,226 +0,0 @@
---
layout: api
page_title: 'HTTP API: Libraries'
description: >-
List of official and community contributed libraries for interacting with the
Vault HTTP API.
---
> [!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.
# Libraries
The programming libraries listed on this page can be used to consume the API more conveniently.
Some are officially maintained while others are provided by the community.
For a step-by-step walkthrough on using these client libraries, see the [developer quickstart](/vault/docs/get-started/developer-qs).
For copy-pastable code examples, see the [vault-examples](https://github.com/hashicorp/vault-examples) repo.
## Official
These libraries are officially maintained by HashiCorp.
### Go
- [Vault Go Client](https://github.com/hashicorp/vault/tree/main/api)
```shell-session
$ go get github.com/hashicorp/vault/api
```
[Example application](https://github.com/hashicorp/hello-vault-go)
### Ruby
@include 'alerts/deprecated.mdx'
- [Vault Ruby Client](https://github.com/hashicorp/vault-ruby)
```shell-session
$ gem install vault
```
## Community
These libraries are provided by the community.
### Ansible
- [ansible-vault](https://github.com/jhaals/ansible-vault) - Lookup plugin without third-party dependencies.
- [Ansible Modules Hashivault](https://pypi.python.org/pypi/ansible-modules-hashivault)
```shell-session
$ pip install ansible-modules-hashivault
```
### C&#35;
- [VaultSharp](https://github.com/rajanadar/VaultSharp)
- Supports .NET 4.6.x, 4.7.x, 4.8.x, .NET Standard 2.x, .NET 6.0, 7.0, and 8.0.
- Supports every auth and secret backend supported by Vault, along with several system APIs.
```shell-session
$ Install-Package VaultSharp
```
- [Vault.NET](https://github.com/Chatham/Vault.NET)
```shell-session
$ Install-Package Vault
```
[Example application](https://github.com/hashicorp/hello-vault-dotnet)
### C++
- [libvault](https://github.com/abedra/libvault)
### Clojure
- [vault-clj](https://github.com/amperity/vault-clj)
### Elixir
- [libvault](https://hex.pm/packages/libvault)
- [vaultex](https://hex.pm/packages/vaultex)
### Erlang
- [canal](https://github.com/rkallos/canal)
### Go
- [vaultgo](https://github.com/mittwald/vaultgo)
```shell-session
$ go get github.com/mittwald/vaultgo
```
### Haskell
- [vault-tool](https://hackage.haskell.org/package/vault-tool)
```shell-session
$ cabal install vault-tool
```
- [gothic](http://hackage.haskell.org/package/gothic)
```shell-session
$ stack install gothic
```
### Java
- [Quarkus Vault](https://github.com/quarkiverse/quarkus-vault)
- [Spring Vault](https://github.com/spring-projects/spring-vault)
- [vault-java-driver](https://github.com/jopenlibs/vault-java-driver)
### Kotlin
- [kault](https://github.com/Hansanto/kault)
- [vault-kotlin](https://github.com/kunickiaj/vault-kotlin)
### Node.js
- [node-vault](https://github.com/kr1sp1n/node-vault)
```shell-session
$ npm install node-vault
```
- [node-vault](https://github.com/shahradelahi/node-vault) (Typescript)
```shell-session
$ npm install @litehex/node-vault
```
- [vaulTS](https://github.com/mittwald/vaulTS) (Github NPM Registry)
```shell-session
$ npm install @mittwald/vaults
```
- [vault-api](https://github.com/SaiHemanthBR/vault-api) (Typescript. Axios-like API)
```shell-session
$ npm install vault-api
```
- [loopback4-vault](https://github.com/sourcefuse/loopback4-vault) (LoopBack 4 Extension)
```shell-session
$ npm i @sourceloop/vault
```
### PHP
- [vault-php-sdk](https://github.com/jippi/vault-php-sdk)
```shell-session
$ composer require jippi/vault-php-sdk
```
- [vault-php-sdk](https://github.com/violuke/vault-php-sdk) extended from jipppi
```shell-session
$ composer require violuke/vault-php-sdk
```
- [vault-php](https://github.com/CSharpRU/vault-php)
```shell-session
$ composer require csharpru/vault-php
```
- [vault-php](https://github.com/mittwald/vaultPHP)
```shell-session
$ composer require mittwald/vault-php
```
### PowerShell
- [Zyborg.Vault](https://github.com/zyborg/Zyborg.Vault)
```PowerShell
Install-Module Zyborg.Vault
```
### Python
- [HVAC](https://github.com/ianunruh/hvac)
```shell-session
$ pip install hvac
```
### R
- [vaultr](https://github.com/vimc/vaultr)
### Rust
- [HashicorpVault](https://crates.io/crates/hashicorp_vault)
- [vaultrs](https://crates.io/crates/vaultrs)
### Scala
- [scala-vault](https://github.com/janstenpickle/scala-vault)
## Experimental
### C#
- [Vault DotNet Client](https://github.com/hashicorp/vault-client-dotnet) -
Note that this is an experimental approach to auto-generating libraries from
OpenAPI content and is not production-ready. We do not have plans to make
this production-ready at this time.
```shell-session
# Install-Package HashiCorp.Vault
```
[Example application](https://github.com/hashicorp/vault-client-dotnet#getting-started)

43
website/content/api-docs/relatedtools.mdx
View file

@ -1,43 +0,0 @@
---
layout: api
page_title: Related Tools
description: Short list of third-party tools that work with or are related to Vault.
---
> [!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.
# Related tools
## HashiCorp tools
- [Vault Agent](/vault/docs/agent-and-proxy/agent) can render Vault secrets either to files or directly into a child process as environment variables using `consul-template` templating syntax
- [Vault Proxy](/vault/docs/agent-and-proxy/proxy) acts as an API Proxy for Vault, and can optionally allow or force interacting clients to use its automatically authenticated token
- [Terraform Vault Provider](https://registry.terraform.io/providers/hashicorp/vault/latest/docs) can read from, write to, and configure Vault from [HashiCorp Terraform](https://www.terraform.io/)
- [consul-template](https://github.com/hashicorp/consul-template) is a template renderer, notifier, and supervisor for HashiCorp Consul and Vault data
- [vault-ssh-helper](https://github.com/hashicorp/vault-ssh-helper) can be used to enable one-time passwords for SSH authentication via Vault
## Third-Party tools
The following list of tools is maintained by the community of Vault users; HashiCorp has not tested or approved them and makes no claims as to their suitability or security.
- [HashiCorp Vault Jenkins plugin](https://plugins.jenkins.io/hashicorp-vault-plugin) - a Jenkins plugin for injecting Vault secrets into the build environment
- [Spring Vault](http://projects.spring.io/spring-vault/) - a Java Spring project for working with Vault secrets
- [vault-exec](https://github.com/kmanning/vault_exec) - a shell wrapper to execute arbitrary scripts using temporary AWS credentials managed by Vault
- [pouch](https://github.com/tuenti/pouch) - A set of tools to manage provisioning of secrets on hosts based on the AppRole authentication method of Vault
- [vault-aws-creds](https://github.com/jantman/vault-aws-creds) - Python helper to export Vault-provided temporary AWS creds into the environment
- [goldfish](https://github.com/Caiyeon/goldfish) - A Vault UI panel written with VueJS and Vault native Go API.
- [vault-migrator](https://github.com/nebtex/vault-migrator) - A tool to migrate data between different Vault storage mechanisms
- [Cryptr](https://github.com/adobe/cryptr) - a desktop Vault UI for Mac, Windows and Linux
- [sequelize-vault](https://github.com/linyows/sequelize-vault) - A Sequelize plugin for easily integrating Vault secrets.
- [ansible-modules-hashivault](https://github.com/TerryHowe/ansible-modules-hashivault) - An Ansible module for configuring most things in Vault including secrets, backends and policies.
- [Docker credential helper](https://github.com/morningconsult/docker-credential-vault-login) - A program that automatically reads Docker credentials from your Vault server and passes them to the Docker daemon to authenticate to your Docker registry when pulling an image
- [Cruise Daytona](https://github.com/cruise-automation/daytona) - An alternative implementation of the Vault client CLI for services and containers. Its core features are the ability to automate authentication, fetching of secrets, and automated token renewal. Support for AWS, GCP, & Kubernetes Vault Auth Backends.
- [Vault-CRD](https://vault.koudingspawn.de/) - Synchronize secrets stored in HashiCorp Vault to Kubernetes Secrets for better GitOps without secrets stored in git manifest files.
- [vsh](https://github.com/fishi0x01/vsh) - Interactive shell with tab-completion. Allows recursive operations on paths. Allows migration of secrets between both KV versions.
- [vault-cli](https://github.com/IBM/vault-cli) - A yaml based automation tool that bootstraps Vault cluster(s) with the desired configuration (namespaces, endpoints, policies, roles, endpoint)
- [vault-go](https://github.com/IBM/vault-go) - Helper Golang Vault types as Kubernetes Custom Resource Definitions (CRD)
- [HashiBox](https://github.com/nunchistudio/hashibox) - Vagrant environment to simulate highly-available cloud with Consul, Nomad, Vault, and optional support for Waypoint. Community & Enterprise supported.
- [vkv](https://github.com/FalcoSuessgott/vkv) - Recursively list key-values entries from Vaults KV2 engine in various formats.
Want to add your own project, or one that you use? Additions are welcome via [pull requests](https://github.com/hashicorp/vault/blob/main/website/content/api-docs/relatedtools.mdx).

218
website/content/api-docs/secret/alicloud.mdx
View file

@ -1,218 +0,0 @@
---
layout: api
page_title: AliCloud - Secrets Engines - HTTP API
description: This is the API documentation for the Vault AliCloud secrets engine.
---
> [!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.
# AliCloud secrets engine (API)
This is the API documentation for the Vault AliCloud secrets engine. For general
information about the usage and operation of the AliCloud secrets engine, please see
the [Vault AliCloud documentation](/vault/docs/secrets/alicloud).
This documentation assumes the AliCloud secrets engine is enabled at the `/alicloud` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.
## Config management
This endpoint configures the root RAM credentials to communicate with AliCloud. AliCloud
will use credentials in the following order:
1. [Environment variables](https://github.com/aliyun/alibaba-cloud-sdk-go/blob/master/sdk/auth/credentials/providers/env.go)
2. A static credential configuration set at this endpoint
3. Instance metadata (recommended)
To use instance metadata, leave the static credential configuration unset.
At present, this endpoint does not confirm that the provided AliCloud credentials are
valid AliCloud credentials with proper permissions.
Please see the [Vault AliCloud documentation](/vault/docs/secrets/alicloud) for
the policies that should be attached to the access key you provide.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/alicloud/config` |
| `GET` | `/alicloud/config` |
### Parameters
- `access_key` (string, required) - The ID of an access key with appropriate policies.
- `secret_key` (string, required) - The secret for that key.
### Sample post request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/alicloud/config
```
### Sample post payload
```json
{
"access_key": "0wNEpMMlzy7szvai",
"secret_key": "PupkTg8jdmau1cXxYacgE736PJj4cA"
}
```
### Sample get response data
```json
{
"access_key": "0wNEpMMlzy7szvai"
}
```
## Role management
The `role` endpoint configures how Vault will generate credentials for users of each role.
### Parameters
- `name` (string, required) – Specifies the name of the role to generate credentials against. This is part of the request URL.
- `remote_policies` (string, optional) - The names and types of a pre-existing policies to be applied to the generate access token. Example: "name:AliyunOSSReadOnlyAccess,type:System".
- `inline_policies` (string, optional) - The policy document JSON to be generated and attached to the access token.
- `role_arn` (string, optional) - The ARN of a role that will be assumed to obtain STS credentials. See [Vault AliCloud documentation](/vault/docs/secrets/alicloud) regarding trusted actors.
- `ttl` (int, optional) - The duration in seconds after which the issued token should expire. Defaults to 0, in which case the value will fallback to the system/mount defaults.
- `max_ttl` (int, optional) - The maximum allowed lifetime of tokens issued using this role.
| Method | Path |
| :------- | :-------------------------- |
| `GET` | `/alicloud/role` |
| `POST` | `/alicloud/role/:role_name` |
| `GET` | `/alicloud/role/:role_name` |
| `DELETE` | `/alicloud/role/:role_name` |
### Sample post request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/alicloud/role/my-application
```
### Sample post payload using policies
```json
{
"remote_policies": [
"name:AliyunOSSReadOnlyAccess,type:System",
"name:AliyunRDSReadOnlyAccess,type:System"
],
"inline_policies": "[{\"Statement\": [{\"Action\": [\"ram:Get*\",\"ram:List*\"],\"Effect\": \"Allow\",\"Resource\": \"*\"}],\"Version\": \"1\"}]"
}
```
### Sample get role response using policies
```json
{
"inline_policies": [
{
"hash": "49796debb24d39b7a61485f9b0c97e04",
"policy_document": {
"Statement": [
{
"Action": ["ram:Get*", "ram:List*"],
"Effect": "Allow",
"Resource": "*"
}
],
"Version": "1"
}
}
],
"max_ttl": 0,
"remote_policies": [
{
"name": "AliyunOSSReadOnlyAccess",
"type": "System"
},
{
"name": "AliyunRDSReadOnlyAccess",
"type": "System"
}
],
"role_arn": "",
"ttl": 0
}
```
### Sample post payload using Assume-Role
```json
{
"role_arn": "acs:ram::5138828231865461:role/hastrustedactors"
}
```
### Sample get role response using Assume-Role
```json
{
"inline_policies": null,
"max_ttl": 0,
"remote_policies": null,
"role_arn": "acs:ram::5138828231865461:role/hastrustedactors",
"ttl": 0
}
```
### Sample list roles response
Performing a `LIST` on the `/alicloud/roles` endpoint will list the names of all the roles Vault contains.
```json
["policy-based", "role-based"]
```
## Generate RAM credentials
This endpoint generates dynamic RAM credentials based on the named role. This
role must be created before queried.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/alicloud/creds/:name` |
### Parameters
- `name` (string, required) – Specifies the name of the role to generate credentials against. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/alicloud/creds/example-role
```
### Sample response for roles using policies
```json
{
"access_key": "0wNEpMMlzy7szvai",
"secret_key": "PupkTg8jdmau1cXxYacgE736PJj4cA"
}
```
### Sample response for roles using Assume-Role
```json
{
"access_key": "STS.L4aBSCSJVMuKg5U1vFDw",
"expiration": "2018-08-15T22:04:07Z",
"secret_key": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pKCNZ9",
"security_token": "CAESrAIIARKAAShQquMnLIlbvEcIxO6wCoqJufs8sWwieUxu45hS9AvKNEte8KRUWiJWJ6Y+YHAPgNwi7yfRecMFydL2uPOgBI7LDio0RkbYLmJfIxHM2nGBPdml7kYEOXmJp2aDhbvvwVYIyt/8iES/R6N208wQh0Pk2bu+/9dvalp6wOHF4gkFGhhTVFMuTDRhQlNDU0pWTXVLZzVVMXZGRHciBTQzMjc0KgVhbGljZTCpnJjwySk6BlJzYU1ENUJuCgExGmkKBUFsbG93Eh8KDEFjdGlvbkVxdWFscxIGQWN0aW9uGgcKBW9zczoqEj8KDlJlc291cmNlRXF1YWxzEghSZXNvdXJjZRojCiFhY3M6b3NzOio6NDMyNzQ6c2FtcGxlYm94L2FsaWNlLyo="
}
```

862
website/content/api-docs/secret/aws.mdx
View file

@ -1,862 +0,0 @@
---
layout: api
page_title: AWS - Secrets Engines - HTTP API
description: This is the API documentation for the Vault AWS secrets engine.
---
> [!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.
# AWS secrets engine (API)
This is the API documentation for the Vault AWS secrets engine. For general
information about the usage and operation of the AWS secrets engine, please see
the [Vault AWS documentation](/vault/docs/secrets/aws).
This documentation assumes the AWS secrets engine is enabled at the `/aws` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.
## Configure root credentials
This endpoint configures the root credentials to communicate with AWS. Credentials
can be configured either with IAM access keys for a privileged AWS account, or using
Plugin Workload Identity Federation (WIF).
### IAM
There are multiple ways to pass root IAM credentials to the Vault server, specified
below with the highest precedence first. If credentials already exist, this will
overwrite them.
The official AWS SDK is used for sourcing credentials from env vars, shared
files, or IAM/ECS instances.
- Static credentials provided to the API as a payload
- [Plugin workload identity federation](/vault/docs/secrets/aws#plugin-workload-identity-federation-wif)
credentials
- Credentials in the `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, and `AWS_REGION`
environment variables **on the server**
- Shared credentials files
- Assigned IAM role or ECS task role credentials
At present, this endpoint does not confirm that the provided AWS credentials are
valid AWS credentials with proper permissions.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/aws/config/root` |
### Parameters
- `max_retries` `(int: -1)` - Number of max retries the client should use for
recoverable errors. The default (`-1`) falls back to the AWS SDK's default
behavior.
- `access_key` `(string: "")` – Specifies the AWS access key ID. Mutually exclusive with
`identity_token_audience`.
- `secret_key` `(string: "")` – Specifies the AWS secret access key. Must be provided with
`access_key`.
- `role_arn` `(string: "")` – <EnterpriseAlert product="vault" inline /> Role ARN to assume
for plugin workload identity federation. Required with `identity_token_audience`.
- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
audience claim value for plugin identity tokens. Must match an allowed audience configured
for the target [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-console).
Mutually exclusive with `access_key`.
- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `region` `(string: <optional>)` – Specifies the AWS region. If not set it
will use the `AWS_REGION` env var, `AWS_DEFAULT_REGION` env var, or
`us-east-1` in that order.
- `iam_endpoint` `(string: <optional>)` – Specifies a custom HTTP IAM endpoint to use.
- `sts_endpoint` `(string: <optional>)` – Specifies a custom HTTP STS endpoint to use.
- `sts_region` `(string: <optional>)` - Specifies a custom STS region to use (should match `sts_endpoint`)
- `sts_fallback_endpoints` `(list: <optional>)` - Specifies an ordered list of fallback STS endpoints to use
- `sts_fallback_regions` `(list: <optional>)` - Specifies an ordered list of fallback STS regions to use (should match fallback endpoints)
- `username_template` `(string: <optional>)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated. The username template is used to generate both IAM usernames (capped at 64 characters)
and STS usernames (capped at 32 characters). Longer usernames result in a 500 error.
To ensure generated usernames are within length limits for both STS/IAM, the template must adequately handle
both conditional cases (see [Conditional Templates](https://pkg.go.dev/text/template)). As an example, if no template
is provided the field defaults to the template below. It is to be noted that, DisplayName is the name of the vault
authenticated user running the AWS credential generation and PolicyName is the name of the Role for which the
credential is being generated for:
```
{{ if (eq .Type "STS") }}
{{ printf "vault-%s-%s" (unix_time) (random 20) | truncate 32 }}
{{ else }}
{{ printf "vault-%s-%s-%s" (printf "%s-%s" (.DisplayName) (.PolicyName) | truncate 42) (unix_time) (random 20) | truncate 64 }}
{{ end }}
```
@include 'rotationfields.mdx'
### Sample payload
```json
{
"access_key": "AKIA...",
"secret_key": "2J+...",
"region": "us-east-1"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/aws/config/root
```
## Read root configuration
This endpoint allows you to read non-secure values that have been configured in the
`config/root` endpoint. In particular, the `secret_key` parameter is never returned.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/aws/config/root` |
### Sample request
```shell-session
$ curl
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/config/root
```
### Sample response
```json
{
"data": {
"access_key": "AKIAEXAMPLE",
"region": "us-west-2",
"iam_endpoint": "https://iam.amazonaws.com",
"sts_endpoint": "https://sts.us-west-2.amazonaws.com",
"max_retries": -1
}
}
```
## Rotate root IAM credentials
When you have configured Vault with static credentials, you can use this
endpoint to have Vault rotate the access key it used. Note that, due to AWS
eventual consistency, after calling this endpoint, subsequent calls from Vault
to AWS may fail for a few seconds until AWS becomes consistent again.
In order to call this endpoint, Vault's AWS access key MUST be the only access
key on the IAM user; otherwise, generation of a new access key will fail. Once
this method is called, Vault will now be the only entity that knows the AWS
secret key is used to access AWS.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/aws/config/rotate-root` |
### Parameters
There are no parameters to this operation.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/aws/config/rotate-root
```
### Sample response
```json
{
"data": {
"access_key": "AKIA..."
}
}
```
The new access key Vault uses is returned by this operation.
## Configure lease
This endpoint configures lease settings for the AWS secrets engine. It is
optional, as there are default values for `lease` and `lease_max`.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/aws/config/lease` |
### Parameters
- `lease` `(string: <required>)` – Specifies the lease value provided as a
string duration with time suffix. "h" (hour) is the largest suffix.
- `lease_max` `(string: <required>)` – Specifies the maximum lease value
provided as a string duration with time suffix. "h" (hour) is the largest
suffix.
### Sample payload
```json
{
"lease": "30m",
"lease_max": "12h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/aws/config/lease
```
## Read lease
This endpoint returns the current lease settings for the AWS secrets engine.
| Method | Path |
| :----- | :------------------ |
| `GET` | `/aws/config/lease` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/config/lease
```
### Sample response
```json
{
"data": {
"lease": "30m0s",
"lease_max": "12h0m0s"
}
}
```
## Create/Update role
This endpoint creates or updates the role with the given `name`. If a role with
the name does not exist, it will be created. If the role exists, it will be
updated with the new attributes.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/aws/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is part of the request URL.
- `credential_type` `(string: <required>)` – Specifies the type of credential to be used when
retrieving credentials from the role. Must be one of `iam_user`,
`assumed_role`, `federation_token`, or `session_token`.
- `role_arns` `(list: [])` – Specifies the ARNs of the AWS roles this Vault role
is allowed to assume. Required when `credential_type` is `assumed_role` and
prohibited otherwise. This is a comma-separated string or JSON array.
- `policy_arns` `(list: [])` – Specifies a list of AWS managed policy ARN. The
behavior depends on the credential type. With `iam_user`, the policies will
be attached to IAM users when they are requested. With `assumed_role` and
`federation_token`, the policy ARNs will act as a filter on what the
credentials can do, similar to `policy_document`.
When `credential_type` is `iam_user` or `federation_token`, at
least one of `policy_arns` or `policy_document` must be specified. This is a
comma-separated string or JSON array. When using `session_token`, this field
is disallowed.
- `policy_document` `(string)` – The IAM policy document for the role. The
behavior depends on the credential type. With `iam_user`, the policy document
will be attached to the IAM user generated and augment the permissions the IAM
user has. With `assumed_role` and `federation_token`, the policy document will
act as a filter on what the credentials can do, similar to `policy_arns`. With
`session_token`, this field is disallowed.
- `iam_groups` `(list: [])` - A list of IAM group names. IAM users generated
against this vault role will be added to these IAM Groups. For a credential
type of `assumed_role` or `federation_token`, the policies sent to the
corresponding AWS call (sts:AssumeRole or sts:GetFederation) will be the
policies from each group in `iam_groups` combined with the `policy_document`
and `policy_arns` parameters.
- `iam_tags` `(list: [])` - A list of strings representing a key/value pair to be used as a
tag for any `iam_user` user that is created by this role. Format is a key and value
separated by an `=` (e.g. `test_key=value`). Note: when using the CLI multiple tags
can be specified in the role configuration by adding another `iam_tags` assignment
in the same command.
- `default_sts_ttl` `(string)` - The default TTL for STS credentials. When a TTL is not
specified when STS credentials are requested, and a default TTL is specified
on the role, then this default TTL will be used. Valid only when
`credential_type` is one of `assumed_role` or `federation_token`.
- `max_sts_ttl` `(string)` - The max allowed TTL for STS credentials (credentials
TTL are capped to `max_sts_ttl`). Valid only when `credential_type` is one of
`assumed_role` or `federation_token`.
- `session_tags` `(list: [])` - The set of key-value pairs to be included as tags for the STS session.
Allowed formats are a map of strings or a list of strings in the format `key=value`.
Valid only when `credential_type` is set to `assumed_role`.
- `external_id` `(string)` - The external ID to use when assuming the role.
Valid only when `credential_type` is set to `assumed_role`.
- `user_path` `(string)` - The path for the user name. Valid only when
`credential_type` is `iam_user`. Default is `/`
- `permissions_boundary_arn` `(string)` - The ARN of the [AWS Permissions
Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
to attach to IAM users created in the role. Valid only when `credential_type`
is `iam_user`. If not specified, then no permissions boundary policy will be
attached.
- `mfa_serial_number` `(string)` - The ARN or hardware device number of the device configured
to the IAM user for multi-factor authentication. Only required if the IAM user has an MFA device
set up in AWS.
Legacy parameters:
These parameters are supported for backwards compatibility only. They cannot be
mixed with the parameters listed above.
- `policy` `(string: <required unless arn provided>)` – Specifies the IAM policy
in JSON format.
- `arn` `(string: <required unless policy provided>)` – Specifies the full ARN
reference to the desired existing policy.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/aws/roles/example-role
```
### Sample payloads
Using an inline IAM policy:
```json
{
"credential_type": "federation_token",
"policy_document": "{\"Version\": \"...\"}"
}
```
Using a Session Token:
```json
{
"credential_type": "session_token"
}
```
Using an ARN:
```json
{
"credential_type": "assumed_role",
"role_arns": "arn:aws:iam::123456789012:role/DeveloperRole"
}
```
Using groups:
```json
{
"credential_type": "assumed_role",
"iam_groups": ["group1", "group2"]
}
```
Using tags:
<Tabs>
<Tab heading="cURL">
```json
{
"credential_type": "iam_user",
"iam_tags": [
"first_key=first_value",
"second_key=second_value"
]
}
```
or
```json
{
"credential_type": "iam_user",
"iam_tags": {
"first_key": "first_value",
"second_key": "second_value"
}
}
```
</Tab>
<Tab heading="CLI">
```bash
vault write aws/roles/example-role \
credential_type=iam_user \
iam_tags="first_key=first_value" \
iam_tags="second_key=second_value" \
```
or
```bash
vault write aws/roles/example-role \
credential_type=iam_user \
iam_tags=@test.json
```
where `test.json` is:
```json
["tag1=42", "tag2=something"]
```
</Tab>
</Tabs>
## Read role
This endpoint queries an existing role by the given name. If the role does not
exist, a 404 is returned.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/aws/roles/:name` |
If invalid role data was supplied to the role from an earlier version of Vault,
then it will show up in the response as `invalid_data`.
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/roles/example-role
```
### Sample responses
For an inline IAM policy:
```json
{
"data": {
"policy_document": "{\"Version\": \"...\"}",
"policy_arns": [],
"credential_types": ["assumed_role"],
"role_arns": [],
"iam_groups": []
}
}
```
For a role ARN:
```json
{
"data": {
"policy_document": "",
"policy_arns": [],
"credential_types": ["assumed_role"],
"role_arns": ["arn:aws:iam::123456789012:role/example-role"],
"iam_groups": []
}
}
```
For IAM groups:
```json
{
"data": {
"policy_document": "",
"policy_arns": [],
"credential_types": ["assumed_role"],
"role_arns": [],
"iam_groups": ["group1", "group2"]
}
}
```
## List roles
This endpoint lists all existing roles in the secrets engine.
| Method | Path |
| :----- | :----------- |
| `LIST` | `/aws/roles` |
### Sample request
```shell-session
$ curl
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/aws/roles
```
### Sample response
```json
{
"data": {
"keys": ["example-role"]
}
}
```
## Delete role
This endpoint deletes an existing role by the given name. If the role does not
exist, a 404 is returned.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `/aws/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/aws/roles/example-role
```
## Generate credentials
This endpoint generates credentials based on the named role. This role must be
created before queried.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/aws/creds/:name` |
| `POST` | `/aws/sts/:name` |
The `/aws/creds` and `/aws/sts` endpoints are almost identical. The exception is
when retrieving credentials for a role that was specified with the legacy `arn`
or `policy` parameter. In this case, credentials retrieved through `/aws/sts`
must be of either the `assumed_role` or `federation_token` types, and
credentials retrieved through `/aws/creds` must be of the `iam_user` type.
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to generate
credentials against. This is part of the request URL.
- `role_arn` `(string)` – The ARN of the role to assume if `credential_type` on
the Vault role is `assumed_role`. Must match one of the allowed role ARNs in
the Vault role. Optional if the Vault role only allows a single AWS role ARN;
required otherwise.
- `role_session_name` `(string)` - The role session name to attach to the assumed role ARN.
`role_session_name` is limited to 64 characters; if exceeded, the `role_session_name` in the
assumed role ARN will be truncated to 64 characters. If `role_session_name` is not provided,
then it will be generated dynamically by default.
- `ttl` `(string: "3600s")` – Specifies the TTL for the use of the STS token.
This is specified as a string with a duration suffix. Valid only when
`credential_type` is `assumed_role` `federation_token`, or `session_token`. When not specified,
the `default_sts_ttl` set for the role will be used. If that is also not set, then
the default value of `3600s` will be used. AWS places limits
on the maximum TTL allowed. See the AWS documentation on the `DurationSeconds`
parameter for
[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
(for `assumed_role` credential types),
[GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html)
(for `federation_token` credential types), or
[GetSessionToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html)
(for `session_token` credential types) for more details.
- `mfa_code` `(string)` - The TOTP generated by the MFA device configured on the IAM user and set
on the Vault role. This is optional based on whether the Vault role has the `mfa_serial_number`
field set or not. Only required if the Vault role has the `mfa_serial_number` set on it.
### Sample AssumeRole request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/creds/example-role
```
### Sample response
```json
{
"data": {
"access_key": "AKIA...",
"secret_key": "xlCs...",
"session_token": null,
"arn": "arn:aws:sts::123456789012:assumed-role/DeveloperRole/some-user-supplied-role-session-name"
}
}
```
### Sample Session Token request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/creds/example-role?mfa_code=123456
```
### Sample response
```json
{
"data": {
"access_key": "AKIA...",
"secret_key": "xlCs...",
"session_token": "FwoG..."
}
}
```
## Create/Update static role
This endpoint creates or updates static role definitions. A static role is a 1-to-1 mapping
with an AWS IAM User, which will be adopted and managed by Vault, including rotating it according
to the configured `rotation_period`.
In addition, this endpoint supports cross-account management.
Vault will use the credentials obtained by assuming a role in another AWS account to perform AWS operations.
Make sure that the IAM role configured in Vault has the necessary permissions to manage the IAM user within the target account.
<Note>
Vault will create a new credential upon configuration, and if the maximum number of access keys already exist,
Vault will rotate the oldest one. Vault must do this to know the credential. At each rotation period, Vault will
continue to prioritize rotating the oldest-existing credential.
For example, if an IAM User has no access keys when onboarded into Vault, then Vault will generate its first access
key for the user. On the first rotation, Vault will generate a second access key for the user. It is only upon the
next rotation cycle that the first access key will now be rotated.
</Note>
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/aws/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `username` `(string: <required>)` – Specifies the username of the IAM user to be managed.
- `rotation_period` `(string/int: <required>)` – Specifies the amount of time
Vault should wait before rotating the password. The minimum is 1 minute. Can be
specified in either `24h` or `86400` format (see [duration format strings](/vault/docs/concepts/duration-format)).
Updating the rotation period will 'reset' the next rotation to occur at `now` + `rotation_period`.
- `assume_role_arn` `(string)` – <EnterpriseAlert product="vault" inline /> Specifies the ARN of the IAM role in the target AWS account that Vault should assume.
When provided, Vault uses the assumed IAM role to generate temporary credentials.
When set, `assume_role_session_name` must also be provided.
- `assume_role_session_name` `(string)` – <EnterpriseAlert product="vault" inline /> Specifies the session name to use when assuming the role.
When set, `assume_role_arn` must also be provided.
- `external_id` `(string)` – <EnterpriseAlert product="vault" inline /> Specifies the external ID to use when assuming the role, if one was set on the IAM role.
### Sample payload
```json
{
"username": "example-user",
"rotation_period": "11h30m"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/aws/static-roles/my-static-role
```
### Sample response
```json
{
"data": {
"assume_role_arn": "",
"assume_role_session_name": "",
"external_id": "",
"id": "AIDA...",
"name": "my-static-role",
"rotation_period": 41400,
"username": "example-user"
}
}
```
## Read static role
This endpoint queries the static role definition.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/aws/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to read.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/aws/static-roles/my-static-role
```
### Sample response
```json
{
"name": "my-static-role",
"username": "example-user",
"rotation_period": "11h30m"
}
```
## List static roles
Use the list static roles endpoint to fetch all existing static roles in the secrets engine.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `/aws/static-roles` |
### Sample request
```shell-session
$ curl
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/aws/static-roles
```
### Sample response
```json
{
"data": {
"keys": ["example-role"]
}
}
```
## Delete static role
This endpoint deletes the static role definition. The user, having been defined externally,
must be cleaned up manually.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/aws/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to
delete. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/aws/static-roles/my-static-role
```
## Get static credentials
This endpoint returns the current credentials based on the named static role.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/aws/static-creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to get
credentials for. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/aws/static-creds/my-static-role
```
### Sample response
```json
{
"access_key": "AKIA...",
"expiration": "2024-10-25T15:02:10Z",
"secret_key": "..."
}
```

377
website/content/api-docs/secret/azure.mdx
View file

@ -1,377 +0,0 @@
---
layout: api
page_title: Azure - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Azure secrets engine.
---
> [!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.
# Azure secrets engine (API)
This is the API documentation for the Vault Azure
secrets engine. For general information about the usage and operation of
the Azure secrets engine, please see the main [Azure secrets documentation][docs].
This documentation assumes the Azure secrets engine is enabled at the `/azure` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.
## Configure access
Configures the credentials required for the plugin to perform API calls
to Azure. These credentials will be used to query roles and create/delete
service principals. Environment variables will override any parameters set in the config.
You can configure the secrets engine with account credentials or using
plugin workload identity federation (WIF).
| Method | Path |
| :----- | :-------------- |
| `POST` | `/azure/config` |
- `subscription_id` (`string: <required>`) - The subscription id for the Azure Active Directory.
This value can also be provided with the AZURE_SUBSCRIPTION_ID environment variable.
- `tenant_id` (`string: <required>`) - The tenant id for the Azure Active Directory.
This value can also be provided with the AZURE_TENANT_ID environment variable.
- `client_id` (`string:""`) - The OAuth2 client id to connect to Azure. This value can also be provided
with the AZURE_CLIENT_ID environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details.
- `client_secret` (`string:""`) - The OAuth2 client secret to connect to Azure. This value can also be
provided with the AZURE_CLIENT_SECRET environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details.
Mutually exclusive with `identity_token_audience`.
- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
audience claim value for plugin identity tokens. Must match the allowed audiences configured
for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app).
Mutually exclusive with `client_secret`.
- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `environment` (`string:""`) - The Azure environment. This value can also be provided with the AZURE_ENVIRONMENT
environment variable. If not specified, Vault will use Azure Public Cloud.
- `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when
rotate-root generates a new client secret. Uses [duration format strings](/vault/docs/concepts/duration-format).
@include 'rotationfields.mdx'
### Sample payload
```json
{
"subscription_id": "94ca80...",
"tenant_id": "d0ac7e...",
"client_id": "e607c4...",
"client_secret": "9a6346...",
"environment": "AzureGermanCloud",
"root_password_ttl": "48d"
}
```
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/azure/config
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault write azure/config \
subscription_id="94ca80..." \
tenant_id="d0ac7e...",
client_id="e607c4...",
client_secret="9a6346...",
environment="AzureGermanCloud",
```
</Tab>
</Tabs>
## Read config
Return the stored configuration, omitting `client_secret`.
| Method | Path |
| :----- | :-------------- |
| `GET` | `/azure/config` |
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/azure/config
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault read azure/config
```
</Tab>
</Tabs>
### Sample response
```json
{
"data": {
"subscription_id": "94ca80...",
"tenant_id": "d0ac7e...",
"client_id": "e607c4...",
"environment": "AzureGermanCloud"
},
...
}
```
## Delete config
Deletes the stored Azure configuration and credentials.
| Method | Path |
| :------- | :-------------- |
| `DELETE` | `/azure/config` |
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/azure/config
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault delete azure/config
```
</Tab>
</Tabs>
## Rotate root
This endpoint generates a new client secret for the root account defined in the config. The
value generated will only be known by Vault.
~> Due to the eventual consistency of Microsoft Azure client secret APIs, the plugin
may briefly stop authenticating to Azure as the password propagates through their
datacenters.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/azure/rotate-root` |
### Parameters
There are no parameters to this operation.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/azure/rotate-root
```
## Create/Update role
Create or update a Vault role. Either `application_object_id` or
`azure_roles` must be provided, and these resources must exist for this
call to succeed. See the Azure secrets [roles docs][roles] for more
information about roles.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/azure/roles/:name` |
### Parameters
- `azure_roles` (`string: ""`) - List of Azure roles to be assigned to the generated service
principal. The array must be in JSON format, properly escaped as a string. See [roles docs][roles]
for details on role definition.
- `azure_groups` (`string: ""`) - List of Azure groups that the generated service principal will be
assigned to. The array must be in JSON format, properly escaped as a string. See [groups docs][groups]
for more details.
- `application_object_id` (`string: ""`) - Application Object ID for an existing service principal that will
be used instead of creating dynamic service principals. If present, `azure_roles` will be ignored. See
[roles docs][roles] for details on role definition.
- `persist_app` (`bool: "false"`) – If set to true, persists the created service principal and application for the lifetime of the role.
Useful for when the Service Principal needs to maintain ownership of objects it creates
- `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using this role.
Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time.
- `max_ttl` (`string: ""`) – Specifies the maximum TTL for service principals generated using this role. Accepts time
suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine max TTL time.
- `explicit_max_ttl` (`string: ""`) – Specifies the explicit maximum lifetime of the lease and service principal.
If not set or set to 0, will use the system default (10 years).
- `permanently_delete` (`bool: false`) - Specifies whether to permanently delete Applications and Service Principals that are dynamically
created by Vault. If `application_object_id` is present, `permanently_delete` must be `false`.
- `sign_in_audience` (`string: ""`) - Specifies the security principal types that are allowed to sign in to the application.
Valid values are: AzureADMyOrg, AzureADMultipleOrgs, AzureADandPersonalMicrosoftAccount, PersonalMicrosoftAccount.
- `tags` (`string: ""`) - A comma-separated string of Azure tags to attach to an application.
### Sample payload
```json
{
"azure_roles": "[
{
\"role_name\": \"Contributor\",
\"scope\": \"/subscriptions/<uuid>/resourceGroups/Website\"
},
{
\"role_id\": \"/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>\",
\"scope\": \"/subscriptions/<uuid>\"
}
]",
"ttl": 3600,
"max_ttl": "24h",
"sign_in_audience": "AzureADMyOrg",
"tags": "team:engineering, environment:development"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/azure/roles/my-role
```
## List roles
Lists all of the roles that are registered with the plugin.
| Method | Path |
| :----- | :------------- |
| `LIST` | `/azure/roles` |
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/azure/roles
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault list azure/roles
```
</Tab>
</Tabs>
### Sample response
```json
{
"data": {
"keys": ["my-role-one", "my-role-two"]
}
}
```
## Delete role
This endpoint deletes an existing role by the given name. If the role does not
exist, a 404 is returned.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `/azure/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/azure/roles/example-role
```
## Generate credentials
This endpoint generates a new service principal based on the named role.
| Method | Path |
| :----- | :------------------- |
| `GET` | `/azure/creds/:name` |
### Parameters
- `name` (`string: <required>`) - Specifies the name of the role to create credentials against.
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/azure/creds/my-role
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault read azure/creds/my-role
```
</Tab>
</Tabs>
### Sample response
```json
{
"data": {
"client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
"client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x",
...
}
}
```
## Revoking/Renewing secrets
See docs on how to [renew](/vault/api-docs/system/leases#renew-lease) and [revoke](/vault/api-docs/system/leases#revoke-lease) leases.
[docs]: /vault/docs/secrets/azure
[roles]: /vault/docs/secrets/azure#roles
[groups]: /vault/docs/secrets/azure#azure-groups

252
website/content/api-docs/secret/cassandra.mdx
View file

@ -1,252 +0,0 @@
---
layout: api
page_title: Cassandra - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Cassandra secrets engine.
---
> [!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.
# Cassandra secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
~> **Deprecation Note:** This backend is deprecated in favor of the
combined databases backend added in v0.7.1. See the API documentation for
the new implementation of this backend at
[Cassandra database plugin HTTP API](/vault/api-docs/secret/databases/cassandra).
This is the API documentation for the Vault Cassandra secrets engine. For
general information about the usage and operation of the Cassandra backend,
please see the
[Vault Cassandra backend documentation](/vault/docs/secrets/databases/cassandra).
This documentation assumes the Cassandra backend is mounted at the `/cassandra`
path in Vault. Since it is possible to enable secrets engines at any location,
please update your API calls accordingly.
## Configure connection
This endpoint configures the connection information used to communicate with
Cassandra.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/cassandra/config/connection` |
### Parameters
- `hosts` `(string: <required>)` – Specifies a set of comma-delineated Cassandra
hosts to connect to.
- `username` `(string: <required>)` – Specifies the username to use for
superuser access.
- `password` `(string: <required>)` – Specifies the password corresponding to
the given username.
- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to
Cassandra.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a
certificate and private key; a certificate, private key, and issuing CA
certificate; or just a CA certificate.
- `pem_json` `(string: "")` – Specifies JSON containing a certificate and
private key; a certificate, private key, and issuing CA certificate; or just a
CA certificate. For convenience format is the same as the output of the
`issue` command from the `pki` backend; see
[the pki documentation](/vault/docs/secrets/pki).
- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use.
- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use.
- `consistency` `(string: "")` – Specifies the consistency option to use. See
the [gocql
definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for
valid options.
TLS works as follows:
- If `tls` is set to true, the connection will use TLS; this happens
automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set
- If `insecure_tls` is set to true, the connection will not perform verification
of the server certificate; this also sets `tls` to true
- If only `issuing_ca` is set in `pem_json`, or the only certificate in
`pem_bundle` is a CA certificate, the given CA certificate will be used for
server certificate verification; otherwise the system CA certificates will be
used
- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`,
client auth will be turned on for the connection
`pem_bundle` should be a PEM-concatenated bundle of a private key + client
certificate, an issuing CA certificate, or both. `pem_json` should contain the
same information; for convenience, the JSON format is the same as that output by
the issue command from the PKI backend.
### Sample payload
```json
{
"hosts": "cassandra1.local",
"username": "user",
"password": "pass"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/cassandra/config/connection
```
## Create role
This endpoint creates or updates the role definition.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/cassandra/roles/:name` |
### Parameters
- `creation_cql` `(string: "")` – Specifies the CQL statements executed to
create and configure the new user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The '{{username}}' and
'{{password}}' values will be substituted; it is required that these
parameters are in single quotes. The default creates a non-superuser user with
no authorization grants.
- `rollback_cql` `(string: "")` – Specifies the CQL statements executed to
attempt a rollback if an error is encountered during user creation. The
default is to delete the user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The '{{username}}' and
'{{password}}' values will be substituted; it is required that these
parameters are in single quotes.
- `lease` `(string: "")` – Specifies the lease value provided as a string
duration with time suffix. "h" hour is the largest suffix.
- `consistency` `(string: "Quorum")` – Specifies the consistency level value
provided as a string. Determines the consistency level used for operations
performed on the Cassandra database.
### Sample payload
```json
{
"creation_cql": "CREATE USER ..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/cassandra/roles/my-role
```
## Read role
This endpoint queries the role definition.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/cassandra/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/cassandra/roles/my-role
```
### Sample response
```json
{
"data": {
"creation_cql": "CREATE USER...",
"rollback_cql": "DROP USER...",
"lease": "12h",
"consistency": "Quorum"
}
}
```
## Delete role
This endpoint deletes the role definition.
| Method | Path | |
| :------- | :----------------------- | --------------- |
| `DELETE` | `/cassandra/roles/:name` | `204 (no body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/cassandra/roles/my-role
```
## Generate credentials
This endpoint generates a new set of dynamic credentials based on the named
role.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/cassandra/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/cassandra/creds/my-role
```
### Sample response
```json
{
"data": {
"username": "vault-root-1430158508-126",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
}
}
```

353
website/content/api-docs/secret/consul.mdx
View file

@ -1,353 +0,0 @@
---
layout: api
page_title: Consul - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Consul secrets engine.
---
> [!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.
# Consul secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
@include 'consul-dataplane-compat.mdx'
This is the API documentation for the Vault Consul secrets engine. For general
information about the usage and operation of the Consul secrets engine, please
see the [Vault Consul documentation](/vault/docs/secrets/consul).
This documentation assumes the Consul secrets engine is enabled at the `/consul`
path in Vault. Since it is possible to enable secrets engines at any location,
please update your API calls accordingly.
## Configure access
This endpoint configures the access information for Consul. This access
information is used so that Vault can communicate with Consul and generate
Consul tokens.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/consul/config/access` |
### Parameters
- `address` `(string: <required>)` – Specifies the address of the Consul
instance, provided as `"host:port"` like `"127.0.0.1:8500"`.
- `scheme` `(string: "http")` – Specifies the URL scheme to use.
- `token` `(string: "")` – Specifies the Consul ACL token to use. This
must be a management type token. If this is not provided, Vault will try to
bootstrap the ACL system of the Consul cluster automatically.
- `ca_cert` `(string: "")` - CA certificate to use when verifying Consul server certificate,
must be x509 PEM encoded.
- `client_cert` `(string: "")` - Client certificate used for Consul's TLS communication,
must be x509 PEM encoded and if this is set you need to also set client_key.
- `client_key` `(string: "")` - Client key used for Consul's TLS communication,
must be x509 PEM encoded and if this is set you need to also set client_cert.
### Sample payload
```json
{
"address": "127.0.0.1:8500",
"scheme": "https",
"token": "adha..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/consul/config/access
```
## Create/Update role
This endpoint creates or updates the Consul role definition. If the role does
not exist, it will be created. If the role already exists, it will receive
updated attributes. At least one of `consul_policies`, `consul_roles`,
`service_identities`, or `node_identities` is required depending on the
Consul version.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/consul/roles/:name` |
### Parameters for consul versions 1.11 and above
- `partition` `(string: "")` - Specifies the Consul admin partition in which the token is generated.
The partition must exist, and the Consul policies or roles assigned to the
Vault role must also exist inside the given partition. If not provided, the partition `default`
is used.
To create a client token within a particular Consul admin partition:
```json
{
"partition": "admin1"
}
```
### Parameters for consul versions 1.8 and above
- `node_identities` `(list: <node identity or identities>)` - The list of node identities to assign to the generated
token. This may be a comma-separated list to attach multiple node identities to a token.
To create a client token with node identities attached:
```json
{
"node_identities": [
"client-1:dc1",
"client-2:dc1"
]
}
```
### Parameters for consul versions 1.7 and above
- `consul_namespace` `(string: "")` - Specifies the Consul namespace in which the token is generated.
The namespace must exist, and the Consul policies or roles assigned to the Vault role must also exist
inside the given Consul namespace. If not provided, the namespace `default` is used.
To create a client token within a particular Consul namespace:
```json
{
"consul_namespace": "ns1"
}
```
### Parameters for consul version 1.5 and above
- `service_identities` `(list: <service identity or identities>)` - The list of service identities to assign to the generated
token. This may be a comma-separated list to attach multiple service identities to a token.
- `consul_roles` `(list: <role or roles>)` – The list of Consul roles to attach to the
token generated by Vault.
To create a client token with roles defined in Consul:
### Sample payload
```json
{
"consul_roles": "role-a,role-b"
}
```
To create a client token with service identities attached:
```json
{
"service_identities": [
"myservice-1:dc1,dc2",
"myservice-2:dc1"
]
}
```
### Parameters for consul versions 1.4 and above
- `name` `(string: <required>)` – Specifies the name of an existing role against
which to create this Consul credential. This is part of the request URL.
- `token_type` <sup>DEPRECATED (1.11)</sup> `(string: "client")` - Specifies the type of token to create
when using this role. Valid values are `"client"` or `"management"`. If a `"management"`
token, the `policy` parameter is not required. Defaults to `"client`". [Deprecated from Consul as of 1.4 and
removed as of Consul 1.11.](/consul/api-docs/acl/legacy)
- `policy` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the base64-encoded ACL policy.
This is required unless the `token_type` is `"management"`. [Deprecated from Consul as of 1.4 and
removed as of Consul 1.11.](/consul/api-docs/acl/legacy)
- `policies` <sup>DEPRECATED (1.11)</sup> `(list: <policy or policies>)` - Same as `consul_policies`.
Deprecated in favor of using `consul_policies`.
- `consul_policies` `(list: <policy or policies>)` – The list of Consul policies to assign
to the generated token. This field is required if using using Consul 1.4.
- `local` `(bool: false)` - Indicates that the token should not be replicated
globally and instead be local to the current datacenter. Only available in Consul
1.4 and greater.
- `ttl` `(duration: "")` – Specifies the TTL for this role. If not
provided, the default Vault TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
provided, the default Vault Max TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
To create a client token with policies defined in Consul:
```json
{
"consul_policies": "policy-1,policy-2"
}
```
### Parameters for consul version below 1.4
- `lease` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the lease for this role.
Uses [duration format strings](/vault/docs/concepts/duration-format). If not
provided, the default Vault lease is used.
- `policy` <sup>DEPRECATED (1.11)</sup> `(string: <policy>)` – Specifies the base64-encoded ACL policy. The
ACL format can be found in the [Consul ACL
documentation](/consul/docs/security/acl/acl-legacy). This is
required unless the `token_type` is `"management"`.
### Sample payload
To create a client token with a base64-encoded policy:
```json
{
"policy": "a2V5ICIi...=="
}
```
To create management tokens:
```json
{
"token_type": "management"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/consul/roles/example-role
```
## Read role
This endpoint queries for information about a Consul role with the given name.
If no role exists with that name, a 404 is returned.
| Method | Path |
| :----- | :-------------------- |
| `GET` | `/consul/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to query. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/consul/roles/example-role
```
### Sample response
```json
{
"data": {
"policy": "abd2...==",
"lease": "1h0m0s",
"token_type": "client"
}
}
```
## List roles
This endpoint lists all existing roles in the secrets engine.
| Method | Path |
| :----- | :-------------- |
| `LIST` | `/consul/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/consul/roles
```
### Sample response
```json
{
"data": {
"keys": ["example-role"]
}
}
```
## Delete role
This endpoint deletes a Consul role with the given name. Even if the role does
not exist, this endpoint will still return a successful response.
| Method | Path |
| :------- | :-------------------- |
| `DELETE` | `/consul/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--request DELETE \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/consul/roles/example-role
```
## Generate credential
This endpoint generates a dynamic Consul token based on the given role
definition.
| Method | Path |
| :----- | :-------------------- |
| `GET` | `/consul/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of an existing role against
which to create this Consul credential. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/consul/creds/example-role
```
### Sample response
```json
{
"data": {
"token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
}
}
```

199
website/content/api-docs/secret/cubbyhole.mdx
View file

@ -1,199 +0,0 @@
---
layout: api
page_title: Cubbyhole - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Cubbyhole secrets engine.
---
> [!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.
# Cubbyhole secrets engine (API)
This is the API documentation for the Vault Cubbyhole secrets engine. For
general information about the usage and operation of the Cubbyhole secrets
engine, please see the
[Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole).
This documentation assumes the Cubbyhole secrets engine is enabled at the
`/cubbyhole` path in Vault. Since it is possible to enable secrets engines at
any location, please update your API calls accordingly.
## Read secret
This endpoint retrieves the secret at the specified location.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/cubbyhole/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL.
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifing a loaded snapshot ID to
read the secret.
### Sample requests
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/cubbyhole/my-secret
```
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
```
### Sample response
```json
{
"auth": null,
"data": {
"foo": "bar"
},
"lease_duration": 0,
"lease_id": "",
"renewable": false
}
```
## List secrets
This endpoint returns a list of secret entries at the specified location.
Folders are suffixed with `/`. The input must be a folder; list on a file will
not return a value. The values themselves are not accessible via this command.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/cubbyhole/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
This is specified as part of the URL.
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifying the loaded snapshot ID from which Vault should read secrets for the provided path.
### Sample requests
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/cubbyhole/my-secret
```
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
```
### Sample response
The example below shows output for a query path of `cubbyhole/` when there are
secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference in the
two entries.
```json
{
"auth": null,
"data": {
"keys": ["foo", "foo/"]
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Create/Update secret
This endpoint stores a secret at the specified location.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/cubbyhole/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secrets to
create/update. This is specified as part of the URL.
- `:key` `(string: "")` – Specifies a key in the payload, paired with an associated value, to
be held at the given location. Multiple key/value pairs can be specified, and
all will be returned on a read operation.
### Sample payload
```json
{
"foo": "bar",
"zip": "zap"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/cubbyhole/my-secret
```
## Recover secret
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/cubbyhole/:path?recover_snapshot_id=:recover_snapshot_id` |
### Query parameters
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/cubbyhole/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
```
## Delete secret
This endpoint deletes the secret at the specified location.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `/cubbyhole/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/cubbyhole/my-secret
```

221
website/content/api-docs/secret/databases/cassandra.mdx
View file

@ -1,221 +0,0 @@
---
layout: api
page_title: Cassandra - Database - Secrets Engines - HTTP API
description: >-
The Cassandra plugin for Vault's database secrets engine generates database
credentials to access Cassandra servers.
---
> [!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.
# Cassandra database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The Cassandra database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Cassandra database.
## Configure connection
In addition to the parameters defined by the [Database
Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `hosts` `(string: <required>)` – Specifies a set of comma-delineated Cassandra
hosts to connect to.
- `port` `(int: 9042)` – Specifies the default port to use if none is provided
as part of the host URI. Defaults to Cassandra's default transport port, 9042.
- `username` `(string: <required>)` – Specifies the username to use for
superuser access.
- `password` `(string: <required>)` – Specifies the password corresponding to
the given username.
- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to
Cassandra.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
- `tls_server_name` `(string: "")` – Specifies the name to use as the SNI host when
connecting to the Cassandra server via TLS.
- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a
certificate and private key; a certificate, private key, and issuing CA
certificate; or just a CA certificate. Only one of `pem_bundle` or `pem_json` can be specified.
- `pem_json` `(string: "")` – Specifies JSON containing a certificate and
private key; a certificate, private key, and issuing CA certificate; or just a
CA certificate. The value in this field must be an encoded JSON object. For convenience format is the
same as the output of the `issue` command from the `pki` secrets engine; see
[the pki documentation](/vault/docs/secrets/pki). Only one of `pem_bundle` or `pem_json` can be specified.
<details>
<summary><b><tt>pem_json</tt> example</b></summary>
```json
{
"certificate": "<client certificate as a PEM>",
"private_key": "<private key as a PEM>",
"ca_chain": ["<CA as a PEM>", "<Additional PEM for the CA chain if needed"]
}
```
If using the Vault CLI, it's probably easiest to write the JSON to a file and then reference the file:
```shell
vault write database/config/cassandra-example <...other fields> pem_json=@/path/to/file.json
```
</details>
- `skip_verification` `(bool: false)` - Skip permissions checks when a connection to Cassandra
is first created. These checks ensure that Vault is able to create roles, but can be resource
intensive in clusters with many roles.
- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use.
- `connect_timeout` `(string: "5s")` – Specifies the timeout to use, both for
connections and in general.
- `local_datacenter` `(string: "")` – If set, enables host selection policy
which will prioritize and use hosts which are in the local datacenter before
hosts in all other datacenters (for example `dc-01`).
- `socket_keep_alive` `(string: "0s")` – the keep-alive period for an active
network connection. If zero, keep-alives are not enabled.
- `consistency` `(string: "")` – Specifies the consistency option to use. See
the [gocql
definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for
valid options.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
<details>
<summary><b>Default Username Template</b></summary>
```
{{ printf "v_%s_%s_%s_%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | truncate 100 | replace "-" "_" | lowercase }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ---------------------------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v_token_myrolename_uszt1n4cyhal4m0xtgx3_1614294836` |
| Example | |
| ------------- | ------------------------------------------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v_amuchlonger_dis_role_name_with__s0t9xb0jsab9nqz7yj40_1614294836` |
</details>
</details>
TLS works as follows:
- If `tls` is set to true, the connection will use TLS; this happens
automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set
- If `insecure_tls` is set to true, the connection will not perform verification
of the server certificate; this also sets `tls` to true
- If only `issuing_ca` is set in `pem_json`, or the only certificate in
`pem_bundle` is a CA certificate, the given CA certificate will be used for
server certificate verification; otherwise the system CA certificates will be
used
- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`,
client auth will be turned on for the connection
`pem_bundle` should be a PEM-concatenated bundle of a private key + client
certificate, an issuing CA certificate, or both. `pem_json` should contain the
same information; for convenience, the JSON format is the same as that output by
the issue command from the PKI secrets engine.
### Sample payload
```json
{
"plugin_name": "cassandra-database-plugin",
"allowed_roles": "readonly",
"hosts": "cassandra1.local",
"username": "user",
"password": "pass"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/cassandra/config/connection
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: [])` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{username}}` and `{{password}}` values will be substituted. If not
provided, defaults to a generic create user statements that creates a
non-superuser.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{username}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed to rollback a create operation in the event of an error. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{username}}` value will be substituted. If not provided, defaults to
a generic drop user statement
- `root_rotation_statements` `(list: [])` - Specifies the database statements
to be executed when rotating the root user's password. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{username}}` value will be substituted. If not provided, defaults to
a reasonable default alter user statement.
~> Prior to Vault 1.7.1 and 1.6.4 the default `root_rotation_statements` does not
allow for usernames with special characters in them due to missing quotes
around the username. To fix this issue in versions prior to Vault 1.7.1/1.6.4,
specify the following `root_rotation_statements`:
```sql
ALTER USER '{{username}}' WITH PASSWORD '{{password}}';
```

118
website/content/api-docs/secret/databases/couchbase.mdx
View file

@ -1,118 +0,0 @@
---
layout: api
page_title: Couchbase - Database - Secrets Engines - HTTP API
description: >-
The Couchbase plugin for Vault's database secrets engine generates database
credentials to access Couchbase servers.
---
> [!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.
# Couchbase database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The Couchbase database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Couchbase database.
## Configure connection
In addition to the parameters defined by the [Database
Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `hosts` `(string: <required>)` – Specifies a set of comma-delimited Couchbase
hosts to connect to. Must use `couchbase://` scheme if `tls` is `true`.
- `username` `(string: <required>)` – Specifies the username for Vault to use.
- `password` `(string: <required>)` – Specifies the password corresponding to
the given username.
- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to
Couchbase.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
- `base64pem` `(string: "")` – Required if `tls` is `true`. Specifies the
certificate authority of the Couchbase server, as a PEM certificate that has
been base64 encoded.
- `bucket_name` `(string: "")` - Required for Couchbase versions prior to 6.5.0. This
is only used to verify vault's connection to the server.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
<details>
<summary><b>Default Username Template</b></summary>
```
V_{{.DisplayName | uppercase | truncate 64}}_{{.RoleName | uppercase | truncate 64}}_{{random 20 | uppercase}}_{{unix_time}}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ---------------------------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `V_TOKEN_MYROLENAME_USZT1N4CYHAL4M0XTGX3_1614294836` |
| Example | |
| ------------- | ------------------------------------------------------------------------------ |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `V_AMUCHLONGER_DISPNAME_ROLE-NAME-WITH-DASHES_S0T9XB0JSAB9NQZ7YJ40_1614294836` |
</details>
</details>
### Sample payload
```json
{
"plugin_name": "couchbase-database-plugin",
"hosts": "couchbase://127.0.0.1",
"username": "user",
"password": "pass",
"allowed-roles": "my-*-role"
}
```
### Sample request
```bash
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/couchbase
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: [])` – Specifies a JSON string containing
Couchbase RBAC roles to assign to created users. Any groups specified must
already exist. Must be a single JSON string. If not provided, defaults to
read-only admin.

112
website/content/api-docs/secret/databases/elasticdb.mdx
View file

@ -1,112 +0,0 @@
---
layout: api
page_title: Elasticsearch - Database - Secrets Engines - HTTP API
description: >-
The Elasticsearch plugin for Vault's database secrets engine generates
database credentials to access Elasticsearch.
---
> [!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.
# Elasticsearch database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The Elasticsearch database plugin is one of the supported plugins for the database
secrets engine. This plugin generates credentials dynamically based on
configured roles for Elasticsearch.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `url` `(string: <required>)` - The URL for Elasticsearch's API (`http://localhost:9200`).
- `username` `(string: <required>)` - The username to be used in the connection URL (`vault`).
- `password` `(string: <required>)` - The password to be used in the connection URL (`pa55w0rd`).
- `ca_cert` `(string: "")` - The path to a PEM-encoded CA cert file to use to verify the Elasticsearch server's identity.
- `ca_path` `(string: "")` - The path to a directory of PEM-encoded CA cert files to use to verify the Elasticsearch server's identity.
- `client_cert` `(string: "")` - The path to the certificate for the Elasticsearch client to present for communication.
- `client_key` `(string: "")` - The path to the key for the Elasticsearch client to use for communication.
- `tls_server_name` `(string: "")` - This, if set, is used to set the SNI host when connecting via TLS.
- `insecure` `(bool: false)` - Not recommended. Default to `false`. Can be set to `true` to disable certificate verification.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `use_old_xpack` `(bool: false)` - Can be set to `true` to use the `/_xpack/security` base API path when managing Elasticsearch. May be required for Elasticsearch server versions prior to 6.
### Sample payload
```json
{
"plugin_name": "elasticsearch-database-plugin",
"allowed_roles": "internally-defined-role,externally-defined-role",
"url": "http://localhost:9200",
"username": "vault",
"password": "myPa55word",
"ca_cert": "/usr/share/ca-certificates/extra/elastic-stack-ca.crt.pem",
"client_cert": "$ES_HOME/config/certs/elastic-certificates.crt.pem",
"client_key": "$ES_HOME/config/certs/elastic-certificates.key.pem"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/my-elasticsearch-database
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(string: <required>)` – Using JSON, either defines an
`elasticsearch_role_definition` or a group of pre-existing `elasticsearch_roles`.
The object specified by the `elasticsearch_role_definition` is the JSON directly
passed through to the Elasticsearch API, so you can pass through anything shown
[here](https://www.elastic.co/guide/en/elasticsearch/reference/6.6/security-api-put-role.html).
For `elasticsearch_roles`, add the names of the roles only. They must pre-exist
in Elasticsearch. Defining roles in Vault is more secure than using pre-existing
roles because a privilege escalation could be performed by editing the roles used
out-of-band in Elasticsearch.
### Sample creation statements
```json
{
"elasticsearch_role_definition": {
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
}
```
```json
{
"elasticsearch_roles": ["pre-existing-role-in-elasticsearch"]
}
```

107
website/content/api-docs/secret/databases/hanadb.mdx
View file

@ -1,107 +0,0 @@
---
layout: api
page_title: HANA - Database - Secrets Engines - HTTP API
description: >-
The HANA plugin for Vault's database secrets engine generates database
credentials to access HANA servers.
---
> [!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.
# HANA database plugin HTTP API
The HANA database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the HANA database.
## Configure connection
In addition to the parameters defined by the [database
secrets engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path | Produces |
| :----- | :----------------------- | -------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the HANA DSN. This field
can be templated and supports passing the username and password
parameters in the following format `{{field_name}}`. A templated connection URL is
required when using root credential rotation.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If &le; `0s`, connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
### Sample payload
```json
{
"plugin_name": "hana-database-plugin",
"allowed_roles": "readonly",
"connection_url": "hdb://{{username}}:{{password}}@localhost:1433",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "username",
"password": "password"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/hana
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}`, `{{password}}`, and `{{expiration}}` values will be
substituted.
- The expiration time will be HANA server time plus the role's `default_ttl`.
If `default_ttl` is 0 or not set, a SQL HdbError 438 will be returned.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided, defaults to dropping the user only if they have
no dependent objects.

818
website/content/api-docs/secret/databases/index.mdx
View file

@ -1,818 +0,0 @@
---
layout: api
page_title: Database - Secrets Engines - HTTP API
description: Top page for database secrets engine information
---
> [!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.
# Database secrets engine (API)
This is the API documentation for the Vault Database secrets engine. For
general information about the usage and operation of the database secrets engine,
please see the
[Vault database secrets engine documentation](/vault/docs/secrets/databases).
This documentation assumes the database secrets engine is enabled at the
`/database` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
## Configure connection
This endpoint configures the connection string used to communicate with the
desired database. In addition to the parameters listed here, each Database
plugin has additional, database plugin specific, parameters for this endpoint.
Please read the HTTP API for the plugin you'd wish to configure to see the full
list of additional parameters.
~> This endpoint distinguishes between `create` and `update` ACL capabilities.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name for this database
connection. This is specified as part of the URL.
- `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use
for this connection.
- `plugin_version` `(string: "")` - Specifies the semantic version of the plugin
to use for this connection.
- `verify_connection` `(bool: true)` – Specifies if the connection is verified
during initial configuration. Defaults to true.
- `allowed_roles` `(list: [])` - List of the roles allowed to use this connection.
Defaults to empty (no roles), if contains a `*` any role can use this connection.
- `root_rotation_statements` `(list: [])` - Specifies the database statements to be
executed to rotate the root user's credentials. See the plugin's API page for more
information on support and formatting for this parameter.
- `password_policy` `(string: "")` - The name of the
[password policy](/vault/docs/concepts/password-policies) to use when generating passwords
for this database. If not specified, this will use a default policy defined as:
20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character.
- `skip_static_role_import_rotation` `(bool: false)` – <EnterpriseAlert inline="true" />
Specifies if a given static account's password should be rotated on creation
of the static roles associated with this database config. This is can be
overridden at the role-level by the static role's [skip_import_rotation](#skip_import_rotation)
field. The default is false.
@include 'rotationfields.mdx'
~> We highly recommended that you use a Vault-specific user rather than the admin user
in your database when configuring the plugin. This user will be used to
create/update/delete users within the database so it will need to have the appropriate
permissions to do so. If the plugin supports
[rotating the root credentials](#rotate-root-credentials), we highly recommended
you perform that action after configuring the plugin. This will change the password
of the user configured in this step. The new password will **not** be viewable by users.
### Common fields
There are several common fields that you will see across many of the database plugins.
Please reference the individual plugin documentation for details on whether these fields
are supported and any additional details about them.
- `connection_url` `(string)` - Specifies the connection string used to connect to the
database. Some plugins use `url` rather than `connection_url`. This allows for simple
templating of the username and password of the root user. Typically, this is done by
including a `{{username}}`, `{{name}}`, and/or `{{password}}` field within the string.
These fields are typically be replaced with the values in the `username` and
`password` fields.
- `username` `(string)` - Specifies the name of the user to use as the "root" user when
connecting to the database. This "root" user is used to create/update/delete users
managed by these plugins, so you will need to ensure that this user has permissions to
manipulate users appropriate to the database. This is typically used in the
`connection_url` field via the templating directive `{{username}}` or `{{name}}`.
- `password` `(string)` - Specifies the password to use when connecting with the
`username`. This value will not be returned by Vault when performing a read upon the
configuration. This is typically used in the `connection_url` field via the templating
directive `{{password}}`.
- `disable_escaping` `(boolean: false)` - Determines whether special characters in the
username and password fields will be escaped. Useful for alternate connection string
formats like ADO. More information regarding this parameter can be found on the
[databases secrets engine docs.](/vault/docs/secrets/databases#disable-character-escaping)
Defaults to `false`.
### Sample payload
```json
{
"plugin_name": "mysql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "vaultuser",
"password": "secretpassword"
}
```
### Sample cURL request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/mysql
```
### Sample CLI request
```shell-session
$ vault write database/config/mysql \
plugin_name="mysql-database-plugin" \
allowed_roles="readonly" \
connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \
username="vaultuser" \
password="secretpassword"
```
### Sample CLI request with ADO-style connection string
```shell-session
$ vault write database/config/mssql \
plugin_name="mssql-database-plugin" \
connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mssql;' \
username="vaultuser" \
password='your#StrongPassword%' \
disable_escaping="true"
```
## Read connection
This endpoint returns the configuration settings for a connection.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/database/config/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to read.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/database/config/mysql
```
### Sample response
```json
{
"data": {
"allowed_roles": ["readonly"],
"connection_details": {
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "vaultuser"
},
"password_policy": "",
"plugin_name": "mysql-database-plugin",
"plugin_version": "",
"root_credentials_rotate_statements": [],
"skip_static_role_import_rotation": false
}
}
```
## List connections
This endpoint returns a list of available connections. Only the connection names
are returned, not any values.
| Method | Path |
| :----- | :----------------- |
| `LIST` | `/database/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/database/config
```
### Sample response
```json
{
"data": {
"keys": ["db-one", "db-two"]
}
}
```
## Delete connection
This endpoint deletes a connection.
| Method | Path |
| :------- | :----------------------- |
| `DELETE` | `/database/config/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to delete.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/database/config/mysql
```
## Reset connection
This endpoint closes a connection and it's underlying plugin and restarts it
with the configuration stored in the barrier.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/database/reset/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to reset.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/database/reset/mysql
```
## Reload plugin
This endpoint performs the same operation as
[reset connection](/vault/api-docs/secret/databases#reset-connection) but for
all connections that reference a specific plugin name. This can be useful to
restart a specific plugin after it's been upgraded in the plugin catalog.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/database/reload/:plugin_name` |
### Parameters
- `plugin_name` `(string: <required>)` – Specifies the name of the plugin for
which all connections should be reset. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/database/reload/postgresql-database-plugin
```
### Sample response
```json
{
"data": {
"connections": ["pg1", "pg2"],
"count": 2
}
}
```
## Rotate root credentials
This endpoint is used to rotate the "root" user credentials stored for
the database connection. This user must have permissions to update its own
password.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/database/rotate-root/:name` |
!> **Use caution:** the root user's password will not be accessible once rotated so it is highly
recommended that you create a user for Vault to utilize rather than using the actual root user.
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to rotate.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/database/rotate-root/mysql
```
## Create role
This endpoint creates or updates a role definition.
~> This endpoint distinguishes between `create` and `update` ACL capabilities.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/database/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `db_name` `(string: <required>)` - The name of the database connection to use
for this role.
- `default_ttl` `(string/int: 0)` - Specifies the TTL for the leases
associated with this role. Accepts time suffixed strings (`1h`) or an integer
number of seconds. Defaults to system/engine default TTL time.
- `max_ttl` `(string/int: 0)` - Specifies the maximum TTL for the leases
associated with this role. Accepts time suffixed strings (`1h`) or an integer
number of seconds. Defaults to `sys/mounts`'s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case](/vault/docs/concepts/tokens#the-general-case).
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. See the plugin's API page
for more information on support and formatting for this parameter.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. See the plugin's API page for more information
on support and formatting for this parameter.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed to rollback a create operation in the event of an error. Not every
plugin type will support this functionality. See the plugin's API page for
more information on support and formatting for this parameter.
- `renew_statements` `(list: [])` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. See the plugin's API page for more information on support and
formatting for this parameter.
@include 'db-secrets-credential-types.mdx'
### Sample payload
```json
{
"db_name": "mysql",
"creation_statements": [
"CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'",
"GRANT SELECT ON *.* TO '{{name}}'@'%'"
],
"default_ttl": "1h",
"max_ttl": "24h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/roles/my-role
```
## Read role
This endpoint queries the role definition.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/database/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/roles/my-role
```
### Sample response
```json
{
"data": {
"creation_statements": [
"CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
"GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"
],
"credential_type": "password",
"db_name": "mysql",
"default_ttl": 3600,
"max_ttl": 86400,
"renew_statements": [],
"revocation_statements": [],
"rollback_statements": []
}
}
```
## List roles
This endpoint returns a list of available roles. Only the role names are
returned, not any values.
| Method | Path |
| :----- | :---------------- |
| `LIST` | `/database/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/database/roles
```
### Sample response
```json
{
"auth": null,
"data": {
"keys": ["dev", "prod"]
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Delete role
This endpoint deletes the role definition.
| Method | Path |
| :------- | :---------------------- |
| `DELETE` | `/database/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/database/roles/my-role
```
## Generate credentials
This endpoint generates a new set of dynamic credentials based on the named
role.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/database/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/creds/my-role
```
### Sample response
```json
{
"data": {
"username": "root-1430158508-126",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
}
}
```
## Create static role
This endpoint creates or updates a static role definition. Static Roles are a
1-to-1 mapping of a Vault Role to a user in a database which are automatically
rotated based on the configured `rotation_period` or `rotation_schedule`.
~> This endpoint distinguishes between `create` and `update` ACL capabilities.
~> Vault will rotate the password when creating a static role. Vault must do
this in order to know the password.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/database/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `username` `(string: <required>)` – Specifies the database username that this
Vault role corresponds to.
- `password` `(string)` – <EnterpriseAlert product="vault" inline />
The password corresponding to the username in the database. Required when using
the Rootless Password Rotation workflow or the Skip Automatic Import Rotation
workflow for static roles.
- `self_managed_password` `(string)` – <EnterpriseAlert product="vault" inline />
The password corresponding to the username in the database. Required when using
the Rootless Password Rotation workflow for static roles. Only enabled for select
DB engines (Postgres). This parameter is deprecated in favor of `password`.
- `db_name` `(string: <required>)` - The name of the database connection to use
for this role.
- `rotation_period` `(string/int)` – Specifies the amount of time Vault should
wait before rotating the password. The minimum is 5 seconds. Uses [duration
format strings](/vault/docs/concepts/duration-format). Mutually exclusive
with `rotation_schedule`.
- `rotation_schedule` `(string)` – A cron-style string that will define the
schedule on which rotations should occur. This should be a "standard"
[cron-style](https://en.wikipedia.org/wiki/Cron) string made of five fields
of which each entry defines the minute, hour, day of month, month, and day of
week respectively. For example, a value of `0 0 * * SAT` will set rotations
to occur on Saturday at 00:00. Vault interprets the schedule in UTC.
Mutually exclusive with `rotation_period`.
~> **Warning**: The `rotation_period` and `rotation_schedule` fields are
mutually exclusive. One of them must be set but not both.
- `rotation_window` `(string/int)` – Specifies the amount of time in which the
rotation is allowed to occur starting from a given `rotation_schedule`. If
the credential is not rotated during this window, due to a failure or
otherwise, it will not be rotated until the next scheduled rotation. The
minimum is 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
Optional when `rotation_schedule` is set and disallowed when `rotation_period`
is set.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for the configured database user. Not every
plugin type will support this functionality. See the plugin's API page for
more information on support and formatting for this parameter.
- `skip_import_rotation` `(bool: false)` – <EnterpriseAlert inline="true" />
Specifies if the static account's password should be rotated on creation of
the static role. This overrides the config-level field
[skip_static_role_import_rotation](#skip_static_role_import_rotation). The
default is false.
@include 'db-secrets-credential-types.mdx'
### Sample payload with rotation period
```json
{
"db_name": "mysql",
"username": "static-database-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_period": "1h"
}
```
### Sample payload with rotation schedule
```json
{
"db_name": "mysql",
"username": "static-database-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_schedule": "0 0 * * SAT",
"rotation_window": "1h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/static-roles/my-static-role
```
## Read static role
This endpoint queries the static role definition.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/database/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to read.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/static-roles/my-static-role
```
### Sample response with rotation period
```json
{
"data": {
"credential_type": "password",
"db_name": "mysql",
"username": "static-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_period": 3600,
"skip_import_rotation": false
}
}
```
### Sample response with rotation schedule
```json
{
"data": {
"credential_type": "password",
"db_name": "mysql",
"username": "static-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_schedule": "0 0 * * SAT",
"rotation_window": 3600,
"skip_import_rotation": false
}
}
```
## List static roles
This endpoint returns a list of available static roles. Only the role names are
returned, not any values.
| Method | Path |
| :----- | :----------------------- |
| `LIST` | `/database/static-roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/database/static-roles
```
### Sample response
```json
{
"auth": null,
"data": {
"keys": ["dev-static", "prod-static"]
}
}
```
## Delete static role
This endpoint deletes the static role definition. The user, having been defined externally,
must be cleaned up manually.
| Method | Path |
| :------- | :----------------------------- |
| `DELETE` | `/database/static-roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to
delete. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/database/static-roles/my-role
```
## Get static credentials
This endpoint returns the current credentials based on the named static role.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/database/static-creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the static role to get
credentials for. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/static-creds/my-static-role
```
### Sample response with rotation period
```json
{
"data": {
"username": "static-user",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
"last_vault_rotation": "2019-05-06T15:26:42.525302-05:00",
"rotation_period": 30,
"ttl": 28
}
}
```
### Sample response with rotation schedule
```json
{
"data": {
"username": "static-user",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
"last_vault_rotation": "2019-05-06T15:26:42.525302-05:00",
"rotation_schedule": "0 0 * * SAT",
"rotation_window": 3600,
"ttl": 5000
}
}
```
## Rotate static role credentials
This endpoint is used to rotate the Static Role credentials stored for a given
role name. While Static Roles are rotated automatically by Vault at configured
rotation periods, users can use this endpoint to manually trigger a rotation to
change the stored password and reset the TTL of the Static Role's password.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/database/rotate-role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the Static Role to
trigger the password rotation for. The name is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/database/rotate-role/my-static-role
```

139
website/content/api-docs/secret/databases/influxdb.mdx
View file

@ -1,139 +0,0 @@
---
layout: api
page_title: Influxdb - Database - Secrets Engines - HTTP API
description: >-
The Influxdb plugin for Vault's database secrets engine generates database
credentials to access Influxdb servers.
---
> [!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.
# Influxdb database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The Influxdb database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Influxdb database.
## Configure connection
In addition to the parameters defined by the [Database
Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `host` `(string: <required>)` – Specifies a Influxdb
host to connect to.
- `port` `(int: 8086)` – Specifies the default port to use if none is provided
as part of the host URI. Defaults to Influxdb's default transport port, 8086.
- `username` `(string: <required>)` – Specifies the username to use for
superuser access.
- `password` `(string: <required>)` – Specifies the password corresponding to
the given username.
- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to
Influxdb.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a
certificate and private key; a certificate, private key, and issuing CA
certificate; or just a CA certificate.
- `pem_json` `(string: "")` – Specifies JSON containing a certificate and
private key; a certificate, private key, and issuing CA certificate; or just a
CA certificate. For convenience format is the same as the output of the
`issue` command from the `pki` secrets engine; see
[the pki documentation](/vault/docs/secrets/pki).
- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
TLS works as follows:
- If `tls` is set to true, the connection will use TLS; this happens
automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set
- If `insecure_tls` is set to true, the connection will not perform verification
of the server certificate; this also sets `tls` to true
- If only `issuing_ca` is set in `pem_json`, or the only certificate in
`pem_bundle` is a CA certificate, the given CA certificate will be used for
server certificate verification; otherwise the system CA certificates will be
used
- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`,
client auth will be turned on for the connection
`pem_bundle` should be a PEM-concatenated bundle of a private key + client
certificate, an issuing CA certificate, or both. `pem_json` should contain the
same information; for convenience, the JSON format is the same as that output by
the issue command from the PKI secrets engine.
### Sample payload
```json
{
"plugin_name": "influxdb-database-plugin",
"allowed_roles": "readonly",
"host": "influxdb1.local",
"username": "user",
"password": "pass"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/influxdb/config/connection
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: [])` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{username}}` and `{{password}}` values will be substituted. If not
provided, defaults to a generic create user statements that creates a
non-superuser.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{username}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed to rollback a create operation in the event of an error. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{username}}` value will be substituted. If not provided, defaults to
a generic drop user statement.

154
website/content/api-docs/secret/databases/mongodb.mdx
View file

@ -1,154 +0,0 @@
---
layout: api
page_title: MongoDB - Database - Secrets Engines - HTTP API
description: >-
The MongoDB plugin for Vault's database secrets engine generates database
credentials to access MongoDB servers.
---
> [!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.
# MongoDB database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The MongoDB database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the MongoDB database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` – Specifies the MongoDB standard
connection string (URI). This field can be templated and supports passing the
username and password parameters in the following format {{field_name}}. A
templated connection URL is required when using root credential rotation.
- `write_concern` `(string: "")` - Specifies the MongoDB [write
concern][mongodb-write-concern]. This is set for the entirety of the session,
maintained for the lifecycle of the plugin process. Must be a serialized JSON
object, or a base64-encoded serialized JSON object. The JSON payload values
map to the values in the [Safe][mgo-safe] struct from the mgo driver.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `tls_certificate_key` `(string: "")` - x509 certificate for connecting to the database.
This must be a PEM encoded version of the private key and the certificate combined.
- `tls_ca` `(string: "")` - x509 CA file for validating the certificate presented by the
MongoDB server. Must be PEM encoded.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
<details>
<summary><b>Default Username Template</b></summary>
```
{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | replace "." "-" | truncate 100 }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ---------------------------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v-token-myrolename-jNFRlKsZZMxJEx60o66i-1614294836` |
| Example | |
| ------------- | ------------------------------------------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v-amuchlonger_dis-role-name-with--jNFRlKsZZMxJEx60o66i-1614294836` |
</details>
</details>
### Sample payload
```json
{
"plugin_name": "mongodb-database-plugin",
"allowed_roles": "readonly",
"connection_url": "mongodb://{{username}}:{{password}}@mongodb.acme.com:27017/admin?ssl=true",
"write_concern": "{ \"wmode\": \"majority\", \"wtimeout\": 5000 }",
"username": "admin",
"password": "Password!"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/mongodb
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(string: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
serialized JSON object, or a base64-encoded serialized JSON object.
The object can optionally contain a `db` string for session connection,
and must contain a `roles` array. This array contains objects that holds
a `role`, and an optional `db` value, and is similar to the BSON document that
is accepted by MongoDB's `roles` field. Vault will transform this array into
such format. For more information regarding the `roles` field, refer to
[MongoDB's documentation](https://docs.mongodb.com/manual/reference/method/db.createUser/).
- `revocation_statements` `(string: "")` – Specifies the database statements to
be executed to revoke a user. Must be a serialized JSON object, or a base64-encoded
serialized JSON object. The object can optionally contain a `db` string. If no
`db` value is provided, it defaults to the `admin` database.
### Sample creation statement
```json
{
"db": "admin",
"roles": [
{
"role": "read",
"db": "foo"
}
]
}
```
### Sample revocation statement
```json
{
"db": "vault-db"
}
```
[mongodb-write-concern]: https://docs.mongodb.com/manual/reference/write-concern/
[mgo-safe]: https://godoc.org/gopkg.in/mgo.v2#Safe

112
website/content/api-docs/secret/databases/mongodbatlas.mdx
View file

@ -1,112 +0,0 @@
---
layout: 'api'
page_title: 'MongoDB Atlas - Database - Secrets Engines - HTTP API'
description: |-
The MongoDB Atlas plugin for Vault's Database Secrets Engine generates MongoDB Database User credentials for MongoDB Atlas.
---
> [!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.
# MongoDB atlas database plugin HTTP API
The MongoDB Atlas plugin is one of the supported plugins for the Database
Secrets Engine. This plugin generates MongoDB Atlas Database User credentials dynamically based on
configured roles.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `public_key` `(string: <required>)` – The Public Programmatic API Key used to authenticate with the MongoDB Atlas API.
- `private_key` `(string: <required>)` - The Private Programmatic API Key used to connect with MongoDB Atlas API.
- `project_id` `(string: <required>)` - The [Project ID](https://docs.atlas.mongodb.com/api/#project-id) the Database User should be created within.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
### Sample payload
```json
{
"plugin_name": "mongodbatlas-database-plugin",
"allowed_roles": "readonly",
"public_key": "aPublicKey",
"private_key": "aPrivateKey",
"project_id": "aProjectID"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/mongodbatlas
```
## Statements
Statements are configured during Vault role creation and are used by the plugin to
determine what is sent to MongoDB Atlas upon user creation, renewal, and
revocation. For more information on configuring roles see the [Role API](/vault/api-docs/secret/databases#create-role)
in the Database Secrets Engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(string: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
serialized JSON object, or a base64-encoded serialized JSON object.
The object can optionally contain a `database_name`, the name of
the authentication database to log into MongoDB. In Atlas deployments of
MongoDB, the options for the authentication database include admin (default) and $external database.
The object must also contain a `roles` array, and from Vault version 1.6.0 (plugin
version 0.2.0) may optionally contain a `scopes` array. The `roles` array
contains objects that hold a series of roles `roleName`, an optional
`databaseName` and `collectionName` value. The `scopes` array determines
which clusters and data lakes the user has access to, and defaults to all
scopes if omitted. For more information regarding the `roles` and `scopes`
fields, refer to [MongoDB Atlas documentation](https://docs.atlas.mongodb.com/reference/api/database-users-create-a-user/).
- `default_ttl` `(string/int): 0` - Specifies the TTL for the leases associated with this role.
Accepts time suffixed strings (`1h`) or an integer number of seconds. Defaults to system/engine default TTL time.
- `max_ttl` `(string/int): 0` - Specifies the maximum TTL for the leases associated with this role. Accepts time
suffixed strings (`1h`) or an integer number of seconds. Defaults to `sys/mounts` default TTL time; this value
is allowed to be less than the mount max TTL (or, if not set, the system max TTL),
but it is not allowed to be longer. See also [The TTL General Case](/vault/docs/concepts/tokens#the-general-case).
### Sample creation statement
```json
{
"database_name": "admin",
"roles": [
{
"databaseName": "admin",
"roleName": "atlasAdmin"
},
{
"collectionName": "acollection",
"roleName": "read"
}
],
"scopes": [
{
"name": "a-cluster",
"type": "CLUSTER"
}
]
}
```

139
website/content/api-docs/secret/databases/mssql.mdx
View file

@ -1,139 +0,0 @@
---
layout: api
page_title: MSSQL - Database - Secrets Engines - HTTP API
description: >-
The MSSQL plugin for Vault's database secrets engine generates database
credentials to access MSSQL servers.
---
> [!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.
# MSSQL database plugin HTTP API
The MSSQL database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the MSSQL database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the MSSQL DSN. This field
can be templated and supports passing the username and password
parameters in the following format {{field_name}}. A templated connection URL is
required when using root credential rotation.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= `0s` connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `contained_db` `(bool: false)` - If set, specifies that the connection being configured is to a
[Contained Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases?view=sql-server-ver15),
like AzureSQL.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
<details>
<summary><b>Default Username Template</b></summary>
```
{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 20) (.RoleName | truncate 20) (random 20) (unix_time) | truncate 128 }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ---------------------------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v-token-myrolename-jNFRlKsZZMxJEx60o66i-1614294836` |
| Example | |
| ------------- | ----------------------------------------------------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v-amuchlonger_dispname-role-name-with-dashe-LUHU9xqm6YNisikA3iCQ-1614294836` |
</details>
</details>
### Sample payload
```json
{
"plugin_name": "mssql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "sqlserver://{{username}}:{{password}}@localhost:1433",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "sa",
"password": "yourStrong(!)Password"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/mssql
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for a given username. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted. The
generated password will be a random alphanumeric 20 character string.

187
website/content/api-docs/secret/databases/mysql-maria.mdx
View file

@ -1,187 +0,0 @@
---
layout: api
page_title: MySQL/MariaDB - Database - Secrets Engines - HTTP API
description: >-
The MySQL/MariaDB plugin for Vault's database secrets engine generates
database credentials to access MySQL and MariaDB servers.
---
> [!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.
# MySQL/MariaDB database plugin HTTP API
@include 'x509-sha1-deprecation.mdx'
The MySQL database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the MySQL database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the MySQL DSN. This field
can be templated and supports passing the username and password
parameters in the following format `{{field_name}}`. A templated connection URL is
required when using root credential rotation.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If &le; 0s connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google
CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to
Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication).
- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use
for IAM authentication. Requires `auth_type` to be `gcp_iam`.
- `use_private_ip` `(boolean: false)` - Enables the option to connect to CloudSQL Instances with Private IP.
Requires `auth_type` to be `gcp_iam`.
- `use_psc` `(boolean: false)` - Enables the option to connect to CloudSQL Instances with Private Service Connect.
Requires `auth_type` to be `gcp_iam`.
- `tls_certificate_key` `(string: "")` - x509 certificate for connecting to the database.
This must be a PEM encoded version of the private key and the certificate combined.
- `tls_ca` `(string: "")` - x509 CA file for validating the certificate presented by the
MySQL server. Must be PEM encoded.
- `tls_server_name` `(string: "")` - Specifies the subject alternative name should be present in the
server's certificate.
- `tls_skip_verify` `(boolean: false)` - When set to true, disables the server certificate verification.
Setting this to true is not recommended for production.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
**Default Username Templates:**
<details>
<summary><b><code>mysql-database-plugin</code></b></summary>
```
{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 10) (.RoleName | truncate 10) (random 20) (unix_time) | truncate 32 }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ---------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v-token-myrolename-jNFRlKsZZMxJE` |
| Example | |
| ------------- | ---------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v-amuchlonge-role-name--LUHU9xqm` |
</details>
</details>
<p></p>
<details>
<summary>
<code>mysql-aurora-database-plugin</code>, <code>mysql-rds-database-plugin</code>, <code>mysql-legacy-database-plugin</code>
</summary>
```
{{ printf "v-%s-%s-%s" (.RoleName | truncate 4) (random 20) | truncate 16 }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ------------------ |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v-myro-jNFRlKsZZ` |
| Example | |
| ------------- | ----------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v-role-b9ODeKsfl` |
</details>
</details>
### Sample payload
```json
{
"plugin_name": "mysql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "root",
"password": "mysql"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/mysql
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted. The
generated password will be a random alphanumeric 20 character string.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.

142
website/content/api-docs/secret/databases/oracle.mdx
View file

@ -1,142 +0,0 @@
---
layout: api
page_title: Oracle - Database - Secrets Engines - HTTP API
description: >-
The Oracle plugin for Vault's database secrets engine generates database
credentials to access Oracle servers.
---
> [!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.
# Oracle database plugin HTTP API
The Oracle database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Oracle database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the Oracle DSN.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= `0s` connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
- `split_statements` `(boolean: true)` - Indicates that the provided statements
specified should be split on semi-colons. Set `split_statements` to true to
specify multiple SQL statements in a single string. Set `split_statements` to
`false` for complex queries such as stored or inline procedures.
- `disconnect_sessions` `(boolean: true)` - Indicates the plugin should
disconnect any open sessions before running revocation statements. If
`disconnect_sessions` is `false`, the revocation statements **must** include
session disconnect logic.
<details>
<summary><b>Default Username Template</b></summary>
```
{{ printf "V_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 30 | uppercase | replace "-" "_" | replace "." "_" }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | -------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `V_TOKEN_MYROLENA_JNFRLKSZZMXJE` |
| Example | |
| ------------- | -------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `V_AMUCHLON_ROLE_NAM_LUHU9XQM6Y` |
</details>
</details>
### Sample payload
```json
{
"plugin_name": "oracle-database-plugin",
"allowed_roles": "readonly",
"connection_url": "{{username}}/{{password}}@localhost:1521/OraDoc.localhost",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "system",
"password": "Oracle"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/oracle
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(string: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted.
- `revocation_statements` `(string: "")` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for a given username. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted. The
generated password will be a random alphanumeric 20 character string.

228
website/content/api-docs/secret/databases/postgresql.mdx
View file

@ -1,228 +0,0 @@
---
layout: api
page_title: PostgreSQL - Database - Secrets Engines - HTTP API
description: >-
The PostgreSQL plugin for Vault's database secrets engine generates database
credentials to access PostgreSQL servers.
---
> [!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.
# PostgreSQL database plugin HTTP API
The PostgreSQL database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the PostgreSQL database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the PostgreSQL DSN. This field
can be templated and supports passing the username and password
parameters in the following format `{{field_name}}`. Certificate authentication
can be used by setting `?sslmode=` to be any of the applicable values as outlined in
the [Postgres SQL documentation](https://www.postgresql.org/docs/11/libpq-ssl.html#LIBPQ-SSL-PROTECTION)
and giving the SSL credentials in the `sslrootcert`, `sslcert` and `sslkey` credentials.
A templated connection URL is required when using root credential rotation. This field
supports both format string types, URI and keyword/value. Both formats support multiple
host connection strings.
Due to how `pgx` works, parameters such as `sslrootcert`, `sslcert`, `sslkey` are treated as paths
on the Vault server.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= `0s`, connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `self_managed` `(boolean: "false")` - <EnterpriseAlert product="vault" inline /> If
set, allows onboarding static roles with a rootless connection configuration. Mutually
exclusive with `username` and `password`. If set, will force `verify_connection` to be false.
- `tls_ca` `(string: "")` - The x509 CA file for validating the certificate
presented by the PostgreSQL server. Must be PEM encoded.
- `tls_certificate` `(string: "")` - The x509 client certificate for connecting
to the database. Must be PEM encoded.
- `private_key` `(string: "")` - The secret key used for the x509 client
certificate. Must be PEM encoded.
- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google
CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to
Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication).
- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use
for IAM authentication. Requires `auth_type` to be `gcp_iam`.
- `use_private_ip` `(boolean: false)` - Enables the option to connect to CloudSQL Instances with Private IP.
Requires `auth_type` to be `gcp_iam`.
- `use_psc` `(boolean: false)` - Enables the option to connect to CloudSQL Instances with Private Service Connect.
Requires `auth_type` to be `gcp_iam`.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
- `password_authentication` `(string: "password")` - When set to "scram-sha-256", passwords will be hashed by Vault and stored as-is by PostgreSQL.
Using "scram-sha-256" requires a minimum version of PostgreSQL 10. Available options are "scram-sha-256" and "password". The default is "password".
When set to "password", passwords will be sent to PostgreSQL in plaintext format and may appear in PostgreSQL logs as-is.
For more information, please refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html#password).
<details>
<summary><b>Default Username Template</b></summary>
```
{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 63 }}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | -------------------------------------------------- |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v-token-myrolena-jNFRlKsZZMxJEx60o66i-1614294836` |
| Example | |
| ------------- | ----------------------------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v-amuchlon-role-nam-LUHU9xqm6YNisikA3iCQ-1614294836` |
</details>
</details>
### Sample payload with URI-format connection string
```json
{
"plugin_name": "postgresql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/postgres",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "username",
"password": "password"
}
```
### Sample payload with Keyword/Value-format connection string
```json
{
"plugin_name": "postgresql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "host=localhost port=5432 user={{username}} password={{password}}",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "username",
"password": "password"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/postgresql
```
### Connection strings with multiple hosts
Postgres supports multiple hosts in the connection string. An example use-case for this might be having
Postgres set up with Replication Manager. However, there are some formatting rules to consider when using
this feature. Please refer to the ["Specifying Multiple Hosts" section of the
official Postgres documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
for more information. Below are two small examples.
#### URI-format Multi-Host string:
```json
{
"connection_url": "postgresql://{{username}}:{{password}}@hostone:5432,hosttwo:5432,hostthree:9999/postgres"
}
```
#### Keyword/Value-format Multi-Host string:
```json
{
"connection_url": "host=hostone,hosttwo,hostthree port=5432,5432,9999 user={{username}} password={{password}} dbname=postgres"
}
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}`, `{{password}}` and `{{expiration}}` values will be
substituted. The generated password will be a random alphanumeric 20 character
string.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed rollback a create operation in the event of an error. Not every
plugin type will support this functionality. Must be a semicolon-separated
string, a base64-encoded semicolon-separated string, a serialized JSON string
array, or a base64-encoded serialized JSON string array. The `{{name}}` value
will be substituted.
- `renew_statements` `(list: [])` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. Must be a semicolon-separated string, a base64-encoded
semicolon-separated string, a serialized JSON string array, or a
base64-encoded serialized JSON string array. The `{{name}}` and
`{{expiration}}` values will be substituted.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for a given username. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted. The
generated password will be a random alphanumeric 20 character string.

79
website/content/api-docs/secret/databases/redis.mdx
View file

@ -1,79 +0,0 @@
---
layout: api
page_title: Redis - Database - Secrets Engines - HTTP API
description: >-
The Redis plugin for Vault's database secrets engine generates [ACL credentials](https://redis.io/docs/manual/security/acl/)
to access Redis servers.
---
> [!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.
# Redis database plugin HTTP API
The Redis database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Redis database.
## Configure connection
In addition to the parameters defined by the [Database
Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `host` `(string: <required>)` – Specifies the host to connect to.
- `port` `(int: <required>)` – Specifies the port number of the connection.
- `username` `(string: <required>)` – Specifies the username for Vault to use.
- `password` `(string: <required>)` – Specifies the password corresponding to the given username.
- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to Redis.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
### Sample payload
```json
{
"plugin_name": "redis-database-plugin",
"host": "localhost://127.0.0.1",
"username": "user",
"password": "pass",
"allowed-roles": "my-*-role"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/redis
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: [])` – Specifies a JSON string containing
[Redis ACL rules](https://redis.io/commands/acl-cat) to assign to created users. If not provided, defaults to
a read-only user that can read any key.

67
website/content/api-docs/secret/databases/rediselasticache.mdx
View file

@ -1,67 +0,0 @@
---
layout: api
page_title: Redis ElastiCache - Database - Secrets Engines - HTTP API
description: >-
The Redis ElastiCache plugin for Vault's database secrets engine generates new passwords for ElastiCache users.
---
> [!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.
# Redis ElastiCache database plugin HTTP API
The Redis ElastiCache database plugin is one of the supported plugins for the database
secrets engine. This plugin generates static database credentials based on
configured roles for the Redis ElastiCache database.
## Configure connection
In addition to the parameters defined by the [Database
Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `url` `(string: <required>)` – Specifies the primary endpoint to connect to.
- `access_key_id` `(string)` – Specifies the IAM `access_key_id` for Vault to use. If omitted, authentication falls back on
the AWS credentials provider chain and tries to infer authentication from the environment.
- `secret_access_key` `(string)` – Specifies the IAM `secret_access_key` corresponding to the given `access_key_id`.
If omitted, authentication falls back on the AWS credentials provider chain and tries to infer authentication from the environment.
- `region` `(string)` – Specifies the AWS region where to ElastiCache cluster is provisioned. If omitted, falls back on
the context from the environment.
### Deprecated parameters
- `username` `(string)` – Use `access_key_id` instead, it is strictly equivalent.
- `password` `(string)` – Use `secret_access_key` instead, it is strictly equivalent.
### Sample payload
```json
{
"plugin_name": "redis-elasticache-database-plugin",
"url": "primary-endpoint.my-cluster.xxx.yyy.cache.amazonaws.com:6379",
"access_key_id": "AKI***",
"secret_access_key": "ktriNYvULAWLzUmTGb***",
"region": "us-east-1",
"allowed-roles": "*"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/my-redis-cluster
```

125
website/content/api-docs/secret/databases/redshift.mdx
View file

@ -1,125 +0,0 @@
---
layout: api
page_title: Redshift - Database - Secrets Engines - HTTP API
description: >-
The Redshift plugin for Vault's database secrets engine generates database
credentials to access the AWS Redshift service.
---
> [!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.
# Redshift database plugin HTTP API
The Redshift database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Redshift database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the Redshift DSN. This field
can be templated and supports passing the username and password
parameters in the following format `{{field_name}}`. A templated connection URL is
required when using root credential rotation.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= `0s` connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
### Sample payload
```json
{
"plugin_name": "redshift-database-plugin",
"allowed_roles": "readonly",
"connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/dev",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "username",
"password": "password"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/redshift
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}`, `{{password}}` and `{{expiration}}` values will be
substituted. The generated password will be a random alphanumeric 20 character
string.
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed rollback a create operation in the event of an error. Not every
plugin type will support this functionality. Must be a semicolon-separated
string, a base64-encoded semicolon-separated string, a serialized JSON string
array, or a base64-encoded serialized JSON string array. The `{{name}}` value
will be substituted.
- `renew_statements` `(list: [])` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. Must be a semicolon-separated string, a base64-encoded
semicolon-separated string, a serialized JSON string array, or a
base64-encoded serialized JSON string array. The `{{name}}` and
`{{expiration}}` values will be substituted.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for a given username. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{password}}` values will be substituted. The
generated password will be a random alphanumeric 20 character string.

155
website/content/api-docs/secret/databases/snowflake.mdx
View file

@ -1,155 +0,0 @@
---
layout: api
page_title: Snowflake - Database - Secrets Engines - HTTP API
description: >-
The Snowflake plugin for Vault's database secrets engine generates database
credentials to access Snowflake servers.
---
> [!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.
# Snowflake database plugin HTTP API
<Warning title="Password authentication removal">
[Snowflake is disabling password authentication for all users](https://www.snowflake.com/en/blog/blocking-single-factor-password-authentification) in
November of 2025. HashiCorp has added support for key pair authentication in
place of passwords.
Vault currently does not support rotate root for key pairs. To manually rotate
key pairs, users can:
- update the root configuration in Vault with the new private key
- update the public key associated with the user in Snowflake
For more information on rotating key pairs, please refer to the official
[Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation).
</Warning>
The Snowflake database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
configured roles for the Snowflake database.
## Configure connection
In addition to the parameters defined by the [Database
Backend](/vault/api-docs/secret/databases#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the Snowflake DSN. This field
can be templated and supports passing the username and password
parameters in the following format `{{field_name}}`. A templated connection URL is
required when using root credential rotation.
- `max_open_connections` `(int: 4)` - Specifies the maximum number of open
connections to the database.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= `0s` connections are reused forever.
- `username` `(string: "")` - The root credential username used in the connection URL.
- `password` `(string: "")` - **Deprecated** The root credential password used in the connection URL.
- `private_key` `(string: "")` - The root credential
[PEM-encoded private key](https://docs.snowflake.com/en/user-guide/key-pair-auth)
for the associated Snowflake user.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username
and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping)
for more information. Defaults to `false`.
### Sample payload
```json
{
"plugin_name": "snowflake-database-plugin",
"allowed_roles": "readonly",
"connection_url": "{{username}}:{{password}}@ecxxxx.west-us-1.azure/db_name",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
"username": "username",
"private_key": "aPrivateKey"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/database/config/snowflake
```
## Statements
Statements are configured during role creation and are used by the plugin to
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` and `{{expiration}}` values will be substituted.
The following values will be substituted depending on the
[credential_type](/vault/api-docs/secret/databases#credential_type) of the role:
- `{{password}}` is substituted for the `password` credential type
- `{{public_key}}` is substituted for the `rsa_private_key` credential type
- `revocation_statements` `(list: [])` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The `{{name}}` value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` – Specifies the database statements to be
executed rollback a create operation in the event of an error. Not every
plugin type will support this functionality. Must be a semicolon-separated
string, a base64-encoded semicolon-separated string, a serialized JSON string
array, or a base64-encoded serialized JSON string array. The `{{name}}` value
will be substituted.
- `renew_statements` `(list: [])` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. Must be a semicolon-separated string, a base64-encoded
semicolon-separated string, a serialized JSON string array, or a
base64-encoded serialized JSON string array. The `{{name}}` and
`{{expiration}}` values will be substituted.
- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for a given username. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The `{{name}}` value will be substituted.
The following values will be substituted depending on the
[credential_type](/vault/api-docs/secret/databases#credential_type) of the role:
- `{{password}}` is substituted for the `password` credential type
- `{{public_key}}` is substituted for the `rsa_private_key` credential type

786
website/content/api-docs/secret/gcp.mdx
View file

@ -1,786 +0,0 @@
---
layout: api
page_title: Google Cloud - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Google Cloud secrets engine.
---
> [!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.
# Google Cloud secrets engine (API)
This is the API documentation for the Vault Google Cloud Platform (GCP)
secrets engine. For general information about the usage and operation of
the GCP secrets engine, please see [these docs](/vault/docs/secrets/gcp).
This documentation assumes the GCP secrets engine is enabled at the `/gcp` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.
## Write config
Use the endpoint to configure shared information for the secrets engine. You can configure
credentials for a privileged service account either with Application Credentials or using
Plugin Workload Identity Federation (WIF).
### IAM
Vault uses the official Google Cloud SDK to source credentials from environment
variables and shared files.
From the highest precedence to lowest, you can pass root credentials to the Vault
server in the following ways:
1. Provide static credentials to the API as a payload.
1. Use [plugin workload identity federation](/vault/docs/secrets/gcp#plugin-workload-identity-federation-wif)
credentials.
1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
as environment variables on the Vault server.
1. Define credentials in shared credential files.
<Warning title="Destructive action">
Passing Vault new root credential overwrites any preexisting root credentials.
</Warning>
| Method | Path |
| :----- | :------------ |
| `POST` | `/gcp/config` |
### Parameters
- `credentials` (`string:""`) - JSON credentials (either file contents or '@path/to/file')
See docs for [alternative ways](/vault/docs/secrets/gcp#setup)
to pass in to this parameter, as well as the
[required permissions](/vault/docs/secrets/gcp#required-permissions). Mutually exclusive with `identity_token_audience`.
@include 'rotationfields.mdx'
- `service_account_email` `(string: "")` – <EnterpriseAlert product="vault" inline /> Service Account
to impersonate for plugin workload identity federation. Required with `identity_token_audience`.
- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
audience claim value for plugin identity tokens. Must match an allowed audience configured
for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare).
Mutually exclusive with `credentials`.
- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `ttl` (`int: 0 || string:"0s"`) – Specifies default config TTL for long-lived credentials
(i.e. service account keys). Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_ttl` (`int: 0 || string:"0s"`)– Specifies the maximum config TTL for long-lived credentials
(i.e. service account keys). Uses [duration format strings](/vault/docs/concepts/duration-format).\*\*
### Sample payload
```json
{
"credentials": "<JSON string>",
"ttl": 3600,
"max_ttl": 14400
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcp/config
```
## Rotate root credentials
Request to rotate the GCP service account credentials used by Vault
for this mount. A new key will be generated for the service account,
replacing the internal value, and then a deletion of the old service
account key is scheduled. Note that this does not create a new service
account, only a new version of the service account key.
This path is only valid if Vault has been configured to use GCP credentials via
the `config/` endpoint where "credentials" were specified. Additionally, the
provided service account must have permissions to create and delete service
account keys.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/gcp/config/rotate-root` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcp/config/rotate-root
```
## Read config
| Method | Path |
| :----- | :------------ |
| `GET` | `/gcp/config` |
Credentials will be omitted from returned data.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/config
```
### Sample response
```json
{
"data": {
"ttl": "1h",
"max_ttl": "4h"
}
}
```
## Create/Update roleset
| Method | Path |
| :----- | :------------------- |
| `POST` | `/gcp/roleset/:name` |
This method allows you to create a roleset or update an existing roleset. See [docs](/vault/docs/secrets/gcp#bindings) for the GCP secrets backend
to learn more about what happens when you create or update a roleset.
**If you update a roleset's bindings, this will effectively revoke any secrets
generated under this roleset.**
### Parameters
- `name` (`string: <required>`): Required. Name of the role. Cannot be updated.
- `secret_type` (`string: "access_token"`): Type of secret generated for this role set. Accepted values: `access_token`, `service_account_key`. Cannot be updated.
- `project` (`string: <required>`): Name of the GCP project that this roleset's service account will belong to. Cannot be updated.
- `bindings` (`string: <required>`): Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string)
- `token_scopes` (`array: []`): List of OAuth scopes to assign to `access_token` secrets generated under this role set (`access_token` role sets only)
### Sample payload
```json
{
"secret_type": "access_token",
"project": "mygcpproject",
"bindings": "...",
"token_scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/bigquery"
]
}
```
#### Sample bindings:
See [bindings format docs](/vault/docs/secrets/gcp#bindings) for more information.
```hcl
resource "//cloudresourcemanager.googleapis.com/projects/mygcpproject" {
roles = [
"roles/viewer"
],
}
resource "//bigquery.googleapis.com/projects/my-project/datasets/mydataset" {
roles = [
"roles/bigquery.dataViewer"
],
}
resource "https://selflink/to/my/resource" {
roles = [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
],
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
```
## Rotate roleset account
| Method | Path | |
| :----- | :-------------------------- | ------------------ |
| `POST` | `/gcp/roleset/:name/rotate` | `204 (empty body)` |
This will rotate the service account this roleset uses to generate secrets.
(this also replaces the key `access_token` roleset). This can be used to invalidate
old secrets generated by the roleset or fix issues if a roleset's service account
(and/or keys) was changed outside of Vault (i.e. through GCP APIs/cloud console).
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/rotate
```
## Rotate roleset account key (`access_token` roleset only)
| Method | Path | |
| :----- | :------------------------------ | ------------------ |
| `POST` | `/gcp/roleset/:name/rotate-key` | `204 (empty body)` |
This will rotate the service account key this roleset uses to generate
access tokens. This does not recreate the roleset service account.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/rotate-key
```
## Read roleset
| Method | Path |
| :----- | :------------------- |
| `GET` | `/gcp/roleset/:name` |
### Parameters
- `name` (`string:<required>`): Name of the roleset to read.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
```
### Sample response
```json
{
"data": {
"secret_type": "access_token",
"service_account_email": "vault-myroleset-XXXXXXXXXX@myproject.gserviceaccounts.com",
"service_account_project": "service-account-project",
"bindings": {
"project/mygcpproject": ["roles/viewer"],
"https://selflink/to/my/resource": [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
]
},
"token_scopes": ["https://www.googleapis.com/auth/cloud-platform"]
}
}
```
## List rolesets
| Method | Path |
| :----- | :-------------- |
| `LIST` | `/gcp/rolesets` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/gcp/rolesets
```
### Sample response
```json
{
"data": {
"keys": ["my-token-roleset", "my-sakey-roleset"]
}
}
```
## Delete roleset
This endpoint deletes an existing roleset by the given name.
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/gcp/roleset/:name` |
### Parameters
- `name` (`string:<required>`): Name of the roleset to delete.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
```
## Create/Update static account
| Method | Path |
| :----- | :-------------------------- |
| `POST` | `/gcp/static-account/:name` |
This method allows you to create a static account or update an existing static account. See [docs](/vault/docs/secrets/gcp#bindings) for the GCP secrets backend
to learn more about what happens when you create or update a static account.
**If you update a static account's bindings, this will effectively revoke any secrets
generated under this static account.**
### Parameters
- `name` (`string: <required>`): Name of the static account. Cannot be updated.
- `secret_type` (`string: "access_token"`): Type of secret generated for this static account. Accepted values: `access_token`, `service_account_key`. Cannot be updated.
- `service_account_email` (`string: <required>`): Email of the GCP service account to manage. Cannot be updated.
- `bindings` (`string`): Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string). Optional.
- `token_scopes` (`array: []`): List of OAuth scopes to assign to `access_token` secrets generated under this static account (`access_token` static accounts only)
### Sample payload
```json
{
"secret_type": "access_token",
"service_account_email": "example@mygcpproject.iam.gserviceaccount.com",
"bindings": "...",
"token_scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/bigquery"
]
}
```
#### Sample bindings:
See [bindings format docs](/vault/docs/secrets/gcp#bindings) for more information.
```hcl
resource "//cloudresourcemanager.googleapis.com/projects/mygcpproject" {
roles = [
"roles/viewer"
],
}
resource "//bigquery.googleapis.com/projects/my-project/datasets/mydataset" {
roles = [
"roles/bigquery.dataViewer"
],
}
resource "https://selflink/to/my/resource" {
roles = [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
],
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcp/static-account/my-token-account
```
## Rotate static account key (`access_token` static account only)
| Method | Path | |
| :----- | :------------------------------ | ------------------------- |
| `POST` | `/gcp/static-account/:name/rotate-key` | `204 (empty body)` |
This will rotate the service account key this static account uses to generate
access tokens. This does not recreate the service account.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcp/static-account/my-token-account/rotate-key
```
## Read static account
| Method | Path |
| :----- | :-------------------------- |
| `GET` | `/gcp/static-account/:name` |
### Parameters
- `name` (`string:<required>`): Name of the static account to read.
This endpoint will only return bindings that are managed through the secrets engine. Bindings
manually managed outside of Vault will not be returned.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/static-account/my-token-account
```
### Sample response
```json
{
"data": {
"secret_type": "access_token",
"service_account_email": "example@mygcpproject.iam.gserviceaccount.com",
"service_account_project": "mygcpproject",
"bindings": {
"project/mygcpproject": ["roles/viewer"],
"https://selflink/to/my/resource": [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
]
},
"token_scopes": ["https://www.googleapis.com/auth/cloud-platform"]
}
}
```
## List static accounts
| Method | Path |
| :----- | :--------------------- |
| `LIST` | `/gcp/static-accounts` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/gcp/static-accounts
```
### Sample response
```json
{
"data": {
"keys": ["my-token-account", "my-sakey-account"]
}
}
```
## Delete static account
This endpoint deletes an existing static account by the given name.
| Method | Path |
| :------- | :-------------------------- |
| `DELETE` | `/gcp/static-account/:name` |
### Parameters
- `name` (`string:<required>`): Name of the static account to delete.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/gcp/static-account/my-token-account
```
## Create/Update impersonated account
| Method | Path |
| :----- | :-------------------------------- |
| `POST` | `/gcp/impersonated-account/:name` |
This method allows you to create an impersonated account or update an existing
impersonated account.
### Parameters
- `name` (`string: <required>`): Name of the impersonated account. Cannot be updated.
- `service_account_email` (`string: <required>`): Email of the GCP service account to
manage. Cannot be updated.
- `token_scopes` (`array: []`): List of OAuth scopes to assign to access tokens
generated under this impersonation account.
- `ttl` (`duration: ""`): Lifetime of the token generated. Defaults to 1 hour and
is limited to a maximum of 12 hours. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"service_account_email": "projectOwner@my-project.iam.gserviceaccount.com",
"token_scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/bigquery"
],
"ttl": "2h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate
```
## Read impersonated account
| Method | Path |
| :----- | :-------------------------------- |
| `GET` | `/gcp/impersonated-account/:name` |
### Parameters
- `name` (`string:<required>`): Name of the impersonated account to read.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate
```
### Sample response
```json
{
"data": {
"service_account_email": "projectOwner@my-project.iam.gserviceaccount.com",
"service_account_project": "my-project",
"token_scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/bigquery"
],
"ttl": 7200
},
}
```
## List impersonated accounts
This endpoint lists the configured Vault roles for impersonated accounts.
| Method | Path |
| :----- | :--------------------- |
| `LIST` | `/gcp/impersonated-accounts` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/gcp/impersonated-accounts
```
### Sample response
```json
{
"data": {
"keys": [
"my-token-impersonate",
"secondary-role"
]
}
}
```
## Delete impersonated account
This endpoint deletes an existing impersonated account by the given name.
| Method | Path |
| :------- | :-------------------------------- |
| `DELETE` | `/gcp/impersonated-account/:name` |
### Parameters
- `name` (`string:<required>`): Name of the impersonated account to delete.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate
```
## Generate secret (IAM service account creds): OAuth2 access token
| Method | Path |
| :------------- | :------------------------------------------------------ |
| `GET` / `POST` | `/gcp/roleset/:roleset/token` |
| `GET` / `POST` | `/gcp/static-account/:static-account/token` |
| `GET` / `POST` | `/gcp/impersonated-account/:impersonated-account/token` |
| `GET` / `POST` | `/gcp/token/:roleset` (deprecated) |
Generates an OAuth2 token with the scopes defined on the roleset, static
account, or impersonated account. This OAuth access token can
be used in GCP API calls, e.g. `curl -H "Authorization: Bearer $TOKEN" ...`
Tokens are non-revocable and non-renewable and have a static TTL of an hour. The TTL configured
for the backend (either through the default system TTLs or through the `config/` endpoint)
do not apply.
### Parameters
- `roleset` (`string:<required>`): Name of an roleset with secret type `access_token` to generate access_token under.
- `static-account` (`string:<required>`): Name of the static account with secret type `access_token` to generate access_token under.
- `impersonated-account` (`string:<required>`): Name of the impersonated account to
generate access_token_under.
### Sample request
**Roleset:**
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/token
```
**Static account:**
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/static-account/my-token-account/token
```
**Impersonated account:**
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate/token
```
### Sample response
```json
{
"request_id": "<uuid>",
"data": {
"token": "ya29.c.Elp5Be3ga87...",
"expires_at_seconds": 1537400046,
"token_ttl": 3599
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Generate secret (IAM service account creds): service account key
| Method | Path |
| :------------- | :---------------------------------------- |
| `GET` / `POST` | `/gcp/roleset/:roleset/key` |
| `GET` / `POST` | `/gcp/static-account/:static-account/key` |
| `GET` / `POST` | `/gcp/key/:roleset` (deprecated) |
If using `GET` ('read'), the optional parameters will be set to their defaults. Use `POST` if you
want to specify different values for these params.
These keys are renewable and have TTL/max TTL as defined by either the backend config
or the system default if config was not defined.
### Parameters
- `roleset` (`string:<required>`): Name of an roleset with secret type `service_account_key` to generate key under.
- `static-account` (`string:<required>`): Name of an static account with secret type `service_account_key` to generate key under.
- `key_algorithm` (`string:"KEY_ALG_RSA_2048"`): Key algorithm used to generate key. Defaults to 2k RSA key
You probably should not choose other values (i.e. 1k), but accepted values are
`enum(`[`ServiceAccountKeyAlgorithm`](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountKeyAlgorithm)`)`
- `key_type` (`string:"TYPE_GOOGLE_CREDENTIALS_FILE`): Private key type to generate. Defaults to JSON credentials file.
Accepted values are `enum(`[`ServiceAccountPrivateKeyType`](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountPrivateKeyType)`)`
- `ttl` (`string: ""`): Specifies the Time To Live value provided using a [duration format string](/vault/docs/concepts/duration-format). If not set, uses the system default value.
### Sample payload
```json
{
"key_algorithm": "KEY_ALG_RSA_2048",
"key_type": "TYPE_GOOGLE_CREDENTIALS_FILE"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcp/roleset/my-key-roleset/key
```
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcp/roleset/my-key-roleset/key
```
### Sample response
```json
{
"request_id": "<uuid>",
"lease_id": "gcp/roleset/my-key-roleset/key/<uuid>",
"renewable": true,
"lease_duration": 3600,
"data": {
"private_key_data": "<base64-encoded private key data>",
"key_algorithm": "TYPE_GOOGLE_CREDENTIALS_FILE",
"key_type": "KEY_ALG_RSA_2048"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Revoking/Renewing secrets
See docs on how to [renew](/vault/api-docs/system/leases#renew-lease) and [revoke](/vault/api-docs/system/leases#revoke-lease) leases.
Note this only applies to service account keys.

881
website/content/api-docs/secret/gcpkms.mdx
View file

@ -1,881 +0,0 @@
---
layout: api
page_title: Google Cloud KMS - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Google Cloud KMS secrets engine.
---
> [!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.
# Google Cloud KMS secrets engine (API)
This is the API documentation for the Vault Google Cloud KMS secrets engine. For
general information about the usage and operation of the Google Cloud KMS
secrets engine, please see the
[Google Cloud KMS documentation](/vault/docs/secrets/gcpkms).
This documentation assumes the Google Cloud KMS secrets engine is enabled at the
`/gcpkms` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
## Configure credentials
This endpoint configures the Google Cloud KMS secrets engine with credentials
and manages the requested scope(s) for authentication.
| Method | Path |
| :----- | :-------------- |
| `POST` | `gcpkms/config` |
### Example policy
```hcl
path "gcpkms/config" {
capabilities = ["create", "update"]
}
```
### Parameters
- `credentials` (`string: ""`) -
The credentials to use for authenticating to Google Cloud. Leave this blank to
use the Default Application Credentials or instance metadata authentication.
- `scopes` (`array<string>: []`) -
The list of full-URL scopes to request when authenticating. By default, this
requests https://www.googleapis.com/auth/cloudkms.
### Sample payload
```json
{
"credentials": "< JSON credentials... >"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/config
```
## Read configuration
This endpoint returns the configuration endpoint for the Google Cloud KMS
secrets engine. The credentials are not returned.
| Method | Path |
| :----- | :-------------- |
| `GET` | `gcpkms/config` |
### Example policy
```hcl
path "gcpkms/config" {
capabilities = ["read"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcpkms/config
```
### Sample response
```json
{
"data": {
"scopes": ["https://www.googleapis.com/auth/cloudkms"]
}
}
```
## Delete configuration
This endpoint deletes any configuration for the Google Cloud KMS secrets engine.
If there is no configuration, the endpoint still returns successfully.
| Method | Path |
| :------- | :-------------- |
| `DELETE` | `gcpkms/config` |
### Example policy
```hcl
path "gcpkms/config" {
capabilities = ["delete"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/gcpkms/config
```
## Decrypt ciphertext
This endpoint uses the named encryption key to decrypt the ciphertext string. For symmetric key types, the provided ciphertext must come from a previous invocation of the `/encrypt` endpoint. For asymmetric key types, the provided ciphertext must be from the encrypt operation against the corresponding key version's public key.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `gcpkms/decrypt/:key` |
### Example policy
```hcl
path "gcpkms/decrypt/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault to use for decryption. This key must already exist in
Vault and must map back to a Google Cloud KMS key.
This is specified as part of the URL.
- `additional_authenticated_data` (`string: ""`) -
Optional data that was specified during encryption of this payload.
- `ciphertext` (`string: ""`) -
Ciphertext to decrypt as previously returned from an encrypt operation. This
must be base64-encoded ciphertext as previously returned from an encrypt
operation.
- `key_version` (`int: 0`) -
Integer version of the crypto key version to use for decryption. This is
required for asymmetric keys. For symmetric keys, Cloud KMS will choose the
correct version automatically.
### Sample payload
```json
{
"ciphertext": "CiQAuMv0..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/decrypt/my-key
```
### Sample response
```json
{
"data": {
"plaintext": "hello world"
}
}
```
## Encrypt plaintext
This endpoint uses the named encryption key to encrypt arbitrary plaintext
string data. The response will be base64-encoded encrypted ciphertext.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `gcpkms/encrypt/:key` |
### Example policy
```hcl
path "gcpkms/encrypt/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault to use for encryption. This key must already exist in
Vault and must map back to a Google Cloud KMS key.
This is specified as part of the URL.
- `additional_authenticated_data` (`string: ""`) -
Optional base64-encoded data that, if specified, must also be provided to
decrypt this payload.
- `key_version` (`int: 0`) -
Integer version of the crypto key version to use for encryption. If unspecified,
this defaults to the latest active crypto key version.
- `plaintext` (`string: ""`) -
Plaintext value to be encrypted. This can be a string or binary, but the size
is limited. See the Google Cloud KMS documentation for information on size
limitations by key types.
### Sample payload
```json
{
"plaintext": "hello world"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/encrypt/my-key
```
### Sample response
```json
{
"data": {
"ciphertext": "CiQAuMv0...",
"key_version": "1"
}
}
```
## Re-Encrypt existing ciphertext
This endpoint uses the named encryption key to re-encrypt the underlying
cryptokey to the latest version for this ciphertext without disclosing the
original plaintext value to the requestor. This is similar to "rewrapping" in
Vault's transit secrets engine.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `gcpkms/reencrypt/:key` |
### Example policy
```hcl
path "gcpkms/reencrypt/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key to use for encryption. This key must already exist in Vault and
Google Cloud KMS.
This is specified as part of the URL.
- `additional_authenticated_data` (`string: ""`) -
Optional data that, if specified, must also be provided during decryption.
- `ciphertext` (`string: ""`) -
Ciphertext to be re-encrypted to the latest key version. This must be ciphertext
that Vault previously generated for this named key.
- `key_version` (`int: 0`) -
Integer version of the crypto key version to use for re-encryption. If unspecified,
this defaults to the latest active crypto key version.
### Sample payload
```json
{
"ciphertext": "CiQAuMv0..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/reencrypt/my-key
```
### Sample response
```json
{
"data": {
"ciphertext": "0lX848IG...",
"key_version": "3"
}
}
```
## Sign digest
This endpoint uses the named encryption key to sign digest string data. The
response will include the base64-encoded signature.
| Method | Path |
| :----- | :----------------- |
| `POST` | `gcpkms/sign/:key` |
### Example policy
```hcl
path "gcpkms/sign/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault to use for signing. This key must already exist in
Vault and must map back to a Google Cloud KMS key.
This is specified as part of the URL.
- `key_version` (`int: <required>`) -
Integer version of the crypto key version to use for signing.
- `digest` (`string: <required>`) -
Digest to sign. This digest is the base64 encoded binary value, and must match
the signing algorithm digest of the Cloud KMS key, for example:
```text
$ openssl dgst -sha256 -binary /my/file | base64
```
### Sample payload
```json
{
"key_version": "1",
"digest": "LoM6lxd8YS+hUynZwrlCG20ViUUqqbNNNmh7HCtOkSc="
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/sign/my-key
```
### Sample response
```json
{
"data": {
"signature": "MGYCMQCOfWMc21jBevoRRo4zGjYsCXer8s..."
}
}
```
## Verify digest
This endpoint uses the named encryption key to verify a signature and digest
string data.
| Method | Path |
| :----- | :------------------- |
| `POST` | `gcpkms/verify/:key` |
### Example policy
```hcl
path "gcpkms/verify/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault to use for verifying. This key must already exist in
Vault and must map back to a Google Cloud KMS key.
This is specified as part of the URL.
- `key_version` (`int: <required>`) -
Integer version of the crypto key version to use for verifying.
- `digest` (`string: <required>`) -
Digest that was signed. This digest is the base64 encoded binary value, and must match
the signing algorithm digest of the Cloud KMS key. For example:
```text
$ openssl dgst -sha256 -binary /my/file | base64
```
- `signature` (`string: <required>`) -
Signature of the digest as returned from a signing operation.
### Sample payload
```json
{
"key_version": "1",
"digest": "LoM6lxd8YS+hUynZwrlCG20ViUUqqbNNNmh7HCtOkSc=",
"signature": "MGQCMEN2rgg6sj2vUEC3IcKDD+UprtMnxDoB3..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/verify/my-key
```
### Sample response
```json
{
"data": {
"valid": true
}
}
```
## List keys
This endpoint lists the named keys available for use in Vault. It does not list
all Google Cloud KMS keys.
| Method | Path |
| :----- | :------------ |
| `LIST` | `gcpkms/keys` |
### Example policy
```hcl
path "gcpkms/keys" {
capabilities = ["list"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/gcpkms/keys
```
### Sample response
```json
{
"data": {
"keys": ["my-key"]
}
}
```
## Create/Update Google Cloud KMS key
This endpoint is used to create or update a Google Cloud KMS key. In addition to
registering the key in Vault, this endpoint will also create the corresponding
Google Cloud KMS key with the given configuration options.
| Method | Path |
| :----- | :----------------- |
| `POST` | `gcpkms/keys/:key` |
### Example policy
```hcl
path "gcpkms/keys/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault.
This is specified as part of the URL.
- `crypto_key` (`string: ""`) -
Name of the crypto key to use. If the given crypto key does not exist, Vault
will try to create it. This defaults to the name of the key given to Vault as
the parameter if unspecified.
- `key_ring` (`string: ""`) -
Full Google Cloud resource ID of the key ring with the project and location
(e.g. projects/my-project/locations/global/keyRings/my-keyring). If the given
key ring does not exist, Vault will try to create it during a create operation.
- `labels` (`map<string>string: nil`) -
Arbitrary key=value labels to apply to the crypto key. To specify multiple
labels, specify this argument multiple times (e.g. labels="a=b" labels="c=d").
- `rotation_period` (`string: ""`) -
Amount of time between crypto key version rotations. This is specified as a
time duration value like 72h (72 hours). The smallest possible value is 24h.
- `protection_level` (`string: "software"`) -
Level of protection to use for the key management. Valid values are `software`
and `hsm`. The default value is `software`. The value cannot be changed after
creation.
- `purpose` (`string: "encrypt_decrypt"`) -
Purpose of the key. Valid options are `asymmetric_decrypt`, `asymmetric_sign`,
and `encrypt_decrypt`. The default value is `encrypt_decrypt`. The value cannot
be changed after creation.
- `algorithm` (`string: "symmetric_encryption"`) -
Algorithm to use for encryption, decryption, or signing. The value depends on
the key purpose. The value cannot be changed after creation. See table below
for the supported algorithms of each purpose.
| Purpose | Supported Algorithms |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `encrypt_decrypt` | `symmetric_encryption` |
| `asymmetric_decrypt` | `rsa_decrypt_oaep_2048_sha256`<br/>`rsa_decrypt_oaep_3072_sha256`<br/>`rsa_decrypt_oaep_4096_sha256` |
| `asymmetric_sign` | `rsa_sign_pss_2048_sha256`<br/>`rsa_sign_pss_3072_sha256`<br/>`rsa_sign_pss_4096_sha256`<br/>`rsa_sign_pkcs1_2048_sha256`<br/>`rsa_sign_pkcs1_3072_sha256`<br/>`rsa_sign_pkcs1_4096_sha256`<br/>`ec_sign_p256_sha256`<br/>`ec_sign_p384_sha384` |
### Sample payload
```json
{
"key_ring": "projects/my-project/locations/my-location/keyRings/my-keyring",
"labels": {
"foo": "bar"
},
"rotation_period": "72h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/keys/my-key
```
## Delete Google Cloud KMS key
This endpoint deletes a key from both Vault and Google Cloud KMS. This will
disable all crypto key versions for this crypto key in Google Cloud KMS and
delete Vault's reference to the crypto key.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `gcpkms/keys/:key` |
### Example policy
```hcl
path "gcpkms/keys/my-key" {
capabilities = ["delete"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/gcpkms/keys/my-key
```
## Read Google Cloud KMS key
This endpoint reads data about a Google Cloud KMS crypto key, including the key
status and current primary key version.
| Method | Path |
| :----- | :----------------- |
| `GET` | `gcpkms/keys/:key` |
### Example policy
```hcl
path "gcpkms/keys/my-key" {
capabilities = ["read"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcpkms/keys/my-key
```
### Sample response
```json
{
"data": {
"id": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key",
"labels": {
"foo": "bar"
},
"next_rotation_time_seconds": 1536613424,
"primary_version": "3",
"purpose": "encrypt_decrypt",
"rotation_schedule_seconds": 259200,
"state": "enabled"
}
}
```
## Read Vault key configuration
This endpoint reads data about a Vault's configuration of the key.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `gcpkms/keys/config/:key` |
### Example policy
```hcl
path "gcpkms/keys/config/my-key" {
capabilities = ["read"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/gcpkms/keys/config/my-key
```
### Sample response
```json
{
"data": {
"name": "my-key",
"crypto_key": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key",
"min_version": 10
}
}
```
## Update Vault key configuration
This endpoint is used to update Vault's information about an existing key.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `gcpkms/keys/config/:key` |
### Example policy
```hcl
path "gcpkms/keys/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key in Vault.
This is specified as part of the URL.
- `min_version` (`int: 0`) -
Minimum allowed crypto key version. If set to a positive value, key versions
less than the given value are not permitted to be used. If set to 0 or a
negative value, there is no minimum key version.
- `max_version` (`int: 0`) -
Maximum allowed crypto key version. If set to a positive value, key versions
greater than the given value are not permitted to be used. If set to 0 or a
negative value, there is no maximum key version.
### Sample payload
```json
{
"min_version": 10
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/keys/config/my-key
```
## Deregister crypto key
This endpoint deregisters an existing reference Vault has to a crypto key in
Google Cloud KMS. The underlying Google Cloud KMS key remains unchanged.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `gcpkms/keys/deregister/:key` |
### Example policy
```hcl
path "gcpkms/keys/deregister/my-key" {
capabilities = ["create", "update"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcpkms/keys/deregister/my-key
```
## Register crypto key
This endpoint registers an existing crypto key in Google Cloud KMS and makes it
available for encryption and decryption in Vault.
| Method | Path |
| :----- | :-------------------------- |
| `POST` | `gcpkms/keys/register/:key` |
### Example policy
```hcl
path "gcpkms/keys/register/my-key" {
capabilities = ["create", "update"]
}
```
### Parameters
- `key` (`string: ""`) -
Name of the key to register in Vault. This will be the named used to refer to
the underlying crypto key when encrypting or decrypting data.
This is specified as part of the URL.
- `crypto_key` (`string: ""`) -
Full resource ID of the crypto key including the project, location, key ring,
and crypto key like "projects/%s/locations/%s/keyRings/%s/cryptoKeys/%s". This
crypto key must already exist in Google Cloud KMS unless verify is set to
"false".
- `verify` (`bool: true`) -
Verify that the given Google Cloud KMS crypto key exists and is accessible
before creating the storage entry in Vault. Set this to "false" if the key will
not exist at creation time.
### Sample payload
```json
{
"crypto_key": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key",
"verify": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/gcpkms/keys/register/my-key
```
## Rotate crypto key
This endpoint rotates a crypto key by creating a new crypto key version for the
corresponding Google Cloud KMS key and updates the new crypto key to be the
primary key for future encryptions.
**It can take up to 2 hours for a new crypto key version to become the primary,
so be sure to issue a read operation if you require new data to be encrypted
with this key.**
| Method | Path |
| :----- | :------------------------ |
| `POST` | `gcpkms/keys/rotate/:key` |
### Example policy
```hcl
path "gcpkms/keys/rotate/my-key" {
capabilities = ["create", "update"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcpkms/keys/rotate/my-key
```
### Sample response
```json
{
"data": {
"key_version": "3"
}
}
```
## Trim KMS key versions
This endpoint deletes old crypto key versions that are older than the key's specified `min_version`.
**Data encrypted with older key versions will be irrecoverable!**
| Method | Path |
| :----- | :---------------------- |
| `POST` | `gcpkms/keys/trim/:key` |
### Example policy
```hcl
path "gcpkms/keys/trim/my-key" {
capabilities = ["create", "update"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/gcpkms/keys/trim/my-key
```

258
website/content/api-docs/secret/identity/entity-alias.mdx
View file

@ -1,258 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Entity Alias - HTTP API'
description: >-
This is the API documentation for managing entity aliases in the identity
store.
---
> [!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.
~> **NOTE:** Be careful in granting permissions to non-readonly identity endpoints.
If a user can modify an entity, they can grant it additional privileges through
policies. If a user can modify an alias they can login with, they can bind it to
an entity with higher privileges.
## Create an entity alias
~> **IMPORTANT NOTE:** Prior to creating any alias it is important to consider the cardinality of the alias' name,
since there are potential security issues to be aware of. The main one revolves around alias reuse. It is possible
for multiple authenticated entities to be bound to the same alias, and therefore gain access to all of its privileges.
It is recommended, whenever possible, to create a unique alias for each entity. This is especially true in the case
of machine generated entities.
This endpoint creates a new alias for an entity.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/identity/entity-alias` |
### Parameters
- `name` `(string: <required>)` - Name of the alias. Name should be the identifier
of the client in the authentication source. For example, if the alias belongs
to userpass backend, the name should be a valid username within userpass
auth method. If the alias belongs to GitHub, it should be the GitHub username. If the alias
belongs to an approle auth method, the name should be a valid RoleID.
- `id` `(string: <optional>)` - ID of the entity alias. If set, updates the
corresponding entity alias.
- `canonical_id` `(string: <required>)` - Entity ID to which this alias belongs to.
- `mount_accessor` `(string: <required>)` - Accessor of the mount to which the
alias should belong to.
- `custom_metadata` `(map<string|string>: <optional>)` - A map of arbitrary string to string valued
user-provided metadata meant to describe the alias.
### Sample payload
```json
{
"name": "testuser",
"canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
"mount_accessor": "auth_userpass_e50b1a44",
"custom_metadata": {
"contact_email": "james_updated@example.com"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity-alias
```
### Sample response
```json
{
"data": {
"canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
"id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31"
}
}
```
## Read entity alias by ID
This endpoint queries the entity alias by its identifier.
| Method | Path |
| :----- | :------------------------------ |
| `GET` | `/identity/entity-alias/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of entity alias.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31
```
### Sample response
```json
{
"data": {
"creation_time": "2017-07-25T21:41:09.820717636Z",
"canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
"custom_metadata": {
"contact_email":"james@example.com"
},
"id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31",
"last_update_time": "2017-07-25T21:41:09.820717636Z",
"local": false,
"metadata": {
"group": "san_francisco",
"region": "west"
},
"mount_accessor": "auth_userpass_e50b1a44",
"mount_path": "userpass/",
"mount_type": "userpass",
"name": "testuser"
}
}
```
## Update entity alias by ID
This endpoint is used to update an existing entity alias.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/identity/entity-alias/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity alias.
- `name` `(string: "")` - Name of the alias. Name should be the identifier
of the client in the authentication source. For example, if the alias belongs
to userpass backend, the name should be a valid username within userpass
backend. If alias belongs to GitHub, it should be the GitHub username.
- `canonical_id` `(string: "")` - Entity ID to which this alias belongs to.
- `mount_accessor` `(string: "")` - Accessor of the mount to which the
alias should belong to.
- `custom_metadata` `(map<string|string>: <optional>)` - A map of arbitrary string to string valued
user-provided metadata meant to describe the alias.
### Sample payload
```json
{
"name": "testuser",
"canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
"mount_accessor": "auth_userpass_e50b1a44"
"custom_metadata": {
"contact_email": "james@example.com"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31
```
### Sample response
```json
{
"data": {
"canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
"id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31"
}
}
```
## Delete entity alias by ID
This endpoint deletes an alias from its corresponding entity.
| Method | Path |
| :------- | :------------------------------ |
| `DELETE` | `/identity/entity-alias/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity alias.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31
```
## List entity aliases by ID
The list by ID endpoint returns the available entity aliases and key data by their identifiers.
| Method | Path |
| :----- | :------------------------------------ |
| `LIST` | `/identity/entity-alias/id` |
| `GET` | `/identity/entity-alias/id?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/entity-alias/id
```
### Sample response
```json
{
"data": {
"key_info": {
"35405f3c-884a-a3ff-4176-bac57f220811": {
"canonical_id": "0c34f097-6313-9597-3b22-91e34072ad28",
"custom_metadata": null,
"local": false,
"mount_accessor": "auth_jwt_e47c5220",
"mount_path": "auth/tfc_jwt/",
"mount_type": "jwt",
"name": "app-alias-1"
},
"4065d8c7-4fa6-db9d-e190-f9644c09638a": {
"canonical_id": "21c6f2bf-b9b0-db44-242f-18bf76cb9ff0",
"custom_metadata": null,
"local": false,
"mount_accessor": "auth_ns_token_79c4d932",
"mount_path": "auth/token/",
"mount_type": "ns_token",
"name": "app-alias-2"
}
},
"keys": [
"35405f3c-884a-a3ff-4176-bac57f220811",
"4065d8c7-4fa6-db9d-e190-f9644c09638a"
]
}
}
```

457
website/content/api-docs/secret/identity/entity.mdx
View file

@ -1,457 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Entity - HTTP API'
description: This is the API documentation for managing entities in the identity store.
---
> [!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.
## Create an entity
This endpoint creates or updates an Entity.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/identity/entity` |
### Parameters
- `name` `(string: entity-<UUID>)` – Name of the entity.
- `id` `(string: <optional>)` - ID of the entity. If set, updates the
corresponding existing entity.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the
entity.
- `policies` `(list of strings: [])` – Policies to be tied to the entity.
- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled
entities' associated tokens cannot be used, but are not revoked.
### Sample payload
```json
{
"metadata": {
"organization": "hashicorp",
"team": "vault"
},
"policies": ["eng-dev", "infra-dev"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity
```
### Sample response
```json
{
"data": {
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
"aliases": null
}
}
```
## Read entity by ID
This endpoint queries the entity by its identifier.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/identity/entity/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
```
### Sample response
```json
{
"data": {
"bucket_key_hash": "177553e4c58987f4cc5d7e530136c642",
"creation_time": "2017-07-25T20:29:22.614756844Z",
"disabled": false,
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
"last_update_time": "2017-07-25T20:29:22.614756844Z",
"metadata": {
"organization": "hashicorp",
"team": "vault"
},
"name": "entity-c323de27-2ad2-5ded-dbf3-0c7ef98bc613",
"aliases": [],
"policies": ["eng-dev", "infra-dev"]
}
}
```
## Update entity by ID
This endpoint is used to update an existing entity.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/identity/entity/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity.
- `name` `(string: entity-<UUID>)` – Name of the entity.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the entity.
- `policies` `(list of strings: [])` – Policies to be tied to the entity.
- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled
entities' associated tokens cannot be used, but are not revoked.
### Sample payload
```json
{
"name": "updatedEntityName",
"metadata": {
"organization": "hashicorp",
"team": "nomad"
},
"policies": ["eng-developers", "infra-developers"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
```
### Sample response
```json
{
"data": {
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
"aliases": null
}
}
```
## Delete entity by ID
This endpoint deletes an entity and all its associated aliases.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/identity/entity/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
```
## Batch delete entities
This endpoint deletes all entities provided.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/identity/entity/batch-delete` |
### Parameters
- `entity_ids` `([]string: <required>)` – List of entity identifiers to delete.
### Sample payload
```json
{
"entity_ids": [
"02fe5a88-912b-6794-62ed-db873ef86a95",
"3bf81bc9-44df-8138-57f9-724a9ae36d04",
"627fba68-98c9-c012-71ba-bfb349585ce1",
"6c4c805b-b384-3d0e-4d51-44d349887b96",
"70a72feb-35d1-c775-0813-8efaa8b4b9b5",
"f1092a67-ce34-48fd-161d-c13a367bc1cd",
"faedd89a-0d82-c197-c8f9-93a3e6cf0cd0"
]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity/batch-delete
```
## List entities by ID
This endpoint returns a list of available entities by their identifiers.
| Method | Path |
| :----- | :------------------------------ |
| `LIST` | `/identity/entity/id` |
| `GET` | `/identity/entity/id?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/entity/id
```
### Sample response
```json
{
"data": {
"keys": [
"02fe5a88-912b-6794-62ed-db873ef86a95",
"3bf81bc9-44df-8138-57f9-724a9ae36d04",
"627fba68-98c9-c012-71ba-bfb349585ce1",
"6c4c805b-b384-3d0e-4d51-44d349887b96",
"70a72feb-35d1-c775-0813-8efaa8b4b9b5",
"f1092a67-ce34-48fd-161d-c13a367bc1cd",
"faedd89a-0d82-c197-c8f9-93a3e6cf0cd0"
]
}
}
```
## Create/Update entity by name
This endpoint is used to create or update an entity by a given name.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/identity/entity/name/:name` |
### Parameters
- `name` `(string: entity-<UUID>)` – Name of the entity.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the entity.
- `policies` `(list of strings: [])` – Policies to be tied to the entity.
- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled
entities' associated tokens cannot be used, but are not revoked.
### Sample payload
```json
{
"metadata": {
"organization": "hashicorp",
"team": "nomad"
},
"policies": ["eng-developers", "infra-developers"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity/name/testentityname
```
### Sample response
```json
{
"data": {
"aliases": null,
"id": "0826be06-577c-a076-3942-2f92da0310ce"
}
}
```
## Read entity by name
This endpoint queries the entity by its name.
| Method | Path |
| :----- | :---------------------------- |
| `GET` | `/identity/entity/name/:name` |
### Parameters
- `name` `(string: <required>)` – Name of the entity.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/entity/name/testentityname
```
### Sample response
```json
{
"data": {
"aliases": [],
"creation_time": "2018-09-19T17:20:27.705389973Z",
"direct_group_ids": [],
"disabled": false,
"group_ids": [],
"id": "0826be06-577c-a076-3942-2f92da0310ce",
"inherited_group_ids": [],
"last_update_time": "2018-09-19T17:20:27.705389973Z",
"merged_entity_ids": null,
"metadata": {
"organization": "hashicorp",
"team": "nomad"
},
"name": "testentityname",
"policies": ["eng-developers", "infra-developers"]
}
}
```
## Delete entity by name
This endpoint deletes an entity and all its associated aliases, given the
entity name.
| Method | Path |
| :------- | :---------------------------- |
| `DELETE` | `/identity/entity/name/:name` |
### Parameters
- `name` `(string: <required>)` – Name of the entity.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/entity/name/testentityname
```
## List entities by name
This endpoint returns a list of available entities by their names.
| Method | Path |
| :----- | :-------------------------------- |
| `LIST` | `/identity/entity/name` |
| `GET` | `/identity/entity/name?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/entity/name
```
### Sample response
```json
{
"data": {
"keys": ["testentityname"]
}
}
```
## Merge entities
This endpoint merges many entities into one entity. Additionally, all groups associated with `from_entity_ids` are merged with those of `to_entity_id`.
Note that if these entities contain aliases sharing the same mount accessor, the merge will fail unless `conflicting_alias_ids_to_keep` is present, and
entities must be merged one at a time. This is because each entity can only have one alias with each mount accessor - for more
information, see the [identity concepts page](/vault/docs/concepts/identity).
<Warning>
We recommended limiting merging to the leader node of your primary cluster.
</Warning>
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/identity/entity/merge` |
### Parameters
- `from_entity_ids` `(list of strings: <required>)` - Entity IDs which need to get
merged.
- `to_entity_id` `(string: <required>)` - Entity ID into which all the other
entities need to get merged.
- `force` `(bool: false)` - Setting this will follow the 'mine' strategy for
merging MFA secrets. If there are secrets of the same type both in entities
that are merged from and in entity into which all others are getting merged,
secrets in the destination will be unaltered. If not set, this API will throw
an error containing all the conflicts.
- `conflicting_alias_ids_to_keep` `(list of strings: [])` - A list of entity
aliases to keep in the case where the to-Entity and from-Entity have aliases
with the same mount accessor. In the case where alias share mount accessors,
the alias ID given in this list will be kept or merged, and the other alias will be deleted.
Note that merges requiring this parameter must have only one from-Entity.
### Sample payload
```json
{
"to_entity_id": "f2cdefbe-f510-a226-77fa-989a48ba6abc",
"from_entity_ids": [
"1ade80ec-ba5c-8eed-91e2-b9dcd41d6fff",
"270976d0-9bab-14a5-4b92-3861805ef73d"
]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/entity/merge
```

199
website/content/api-docs/secret/identity/group-alias.mdx
View file

@ -1,199 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Group Alias - HTTP API'
description: >-
This is the API documentation for managing the group aliases in the identity
store.
---
> [!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.
## Create a group alias
This endpoint creates or updates a group alias.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/identity/group-alias` |
### Parameters
- `name` `(string: entity-<UUID>)` – Name of the group alias.
- `id` `(string: <optional>)` - ID of the group alias. If set, updates the
corresponding existing group alias.
- `mount_accessor` `(string: "")` – Mount accessor which this alias belongs
to.
- `canonical_id` `(string: "")` - ID of the group to which this is an alias.
### Sample payload
```json
{
"canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
"mount_accessor": "auth_github_232a90dc",
"name": "dev-team"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/group-alias
```
### Sample response
```json
{
"data": {
"canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
"id": "ca726050-d8ac-6f1f-4210-3b5c5b613824"
}
}
```
## Update group alias by ID
This endpoint is used to update an existing group alias.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/identity/group-alias/id/:id` |
### Parameters
- `id` `(string: <optional>)` - ID of the group alias.
- `name` `(string: entity-<UUID>)` – Name of the group alias.
- `mount_accessor` `(string: "")` – Mount accessor which this alias belongs
to.
- `canonical_id` `(string: "")` - ID of the group to which this is an alias.
### Sample payload
```json
{
"canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
"mount_accessor": "auth_github_232a90dc",
"name": "dev-team"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```
### Sample response
```json
{
"data": {
"canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
"id": "ca726050-d8ac-6f1f-4210-3b5c5b613824"
}
}
```
## Read group alias by ID
This endpoint queries the group alias by its identifier.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/identity/group-alias/id/:id` |
### Parameters
- `id` `(string: <required>)` – ID of the group alias.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```
### Sample response
```json
{
"data": {
"canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
"creation_time": "2017-11-13T20:09:41.661694Z",
"id": "ca726050-d8ac-6f1f-4210-3b5c5b613824",
"last_update_time": "2017-11-13T20:09:41.661694Z",
"merged_from_canonical_ids": null,
"metadata": null,
"mount_accessor": "auth_github_232a90dc",
"mount_path": "",
"mount_type": "github",
"name": "dev-team"
}
}
```
## Delete group alias by ID
This endpoint deletes a group alias.
| Method | Path |
| :------- | :----------------------------- |
| `DELETE` | `/identity/group-alias/id/:id` |
### Parameters
- `id` `(string: <required>)` – ID of the group alias.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```
## List group alias by ID
This endpoint returns a list of available group aliases by their identifiers.
| Method | Path |
| :----- | :----------------------------------- |
| `LIST` | `/identity/group-alias/id` |
| `GET` | `/identity/group-alias/id?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/group-alias/id
```
### Sample response
```json
{
"data": {
"keys": ["ca726050-d8ac-6f1f-4210-3b5c5b613824"]
}
}
```

388
website/content/api-docs/secret/identity/group.mdx
View file

@ -1,388 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Group - HTTP API'
description: This is the API documentation for managing groups in the identity store.
---
> [!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.
~> **NOTE:** Be careful in granting permissions to non-readonly identity group
endpoints. If a user can modify group membership, they can add their entity to
a group with higher privileges.
## Create a group
This endpoint creates or updates a Group.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/identity/group` |
### Parameters
- `name` `(string: entity-<UUID>)` – Name of the group. If set (and
ID is not set), updates the corresponding existing group.
- `id` `(string: <optional>)` - ID of the group. If set, updates the
corresponding existing group.
- `type` `(string: "internal")` - Type of the group, `internal` or `external`.
Defaults to `internal`.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the
group.
- `policies` `(list of strings: [])` – Policies to be tied to the group.
- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as
group members.
- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as
group members.
### Sample payload
```json
{
"metadata": {
"hello": "world"
},
"policies": ["grouppolicy1", "grouppolicy2"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/group
```
### Sample response
```json
{
"data": {
"id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
"name": "group_ab813d63"
}
}
```
## Read group by ID
This endpoint queries the group by its identifier.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/identity/group/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```
### Sample response
```json
{
"data": {
"alias": {},
"creation_time": "2017-11-13T19:36:47.102945Z",
"id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
"last_update_time": "2017-11-13T19:36:47.102945Z",
"member_entity_ids": [],
"member_group_ids": null,
"metadata": {
"hello": "world"
},
"modify_index": 1,
"name": "group_ab813d63",
"policies": ["grouppolicy1", "grouppolicy2"],
"type": "internal"
}
}
```
## Update group by ID
This endpoint is used to update an existing group.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/identity/group/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the entity.
- `name` `(string: entity-<UUID>)` – Name of the group.
- `type` `(string: "internal")` - Type of the group, `internal` or `external`.
Defaults to `internal`.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the
group.
- `policies` `(list of strings: [])` – Policies to be tied to the group.
- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as
group members.
- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as
group members.
### Sample payload
```json
{
"name": "testgroupname",
"metadata": {
"hello": "everyone"
},
"policies": ["grouppolicy2", "grouppolicy3"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```
### Sample response
```json
{
"data": {
"id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
"name": "testgroupname"
}
}
```
## Delete group by ID
This endpoint deletes a group.
| Method | Path |
| :------- | :----------------------- |
| `DELETE` | `/identity/group/id/:id` |
### Parameters
- `id` `(string: <required>)` – Identifier of the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```
## List groups by ID
This endpoint returns a list of available groups by their identifiers.
| Method | Path |
| :----- | :----------------------------- |
| `LIST` | `/identity/group/id` |
| `GET` | `/identity/group/id?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/group/id
```
### Sample response
```json
{
"data": {
"keys": [
"052567cf-1580-6f20-50c8-d38bc46dae6e",
"26da8035-6691-b89e-67ac-ebf9ea7f9893",
"363926d8-dd8b-c9f0-21f8-7b248be80ce1",
"5c4a5720-7408-c113-1dcc-9ede725d0ac8",
"d55e0f34-5c16-38ae-87af-324c9b656c43",
"e4e56e04-0dec-9b68-9b20-a450975d898e"
]
}
}
```
## Create/Update group by name
This endpoint is used to create or update a group by its name.
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/identity/group/name/:name` |
### Parameters
- `name` `(string: entity-<UUID>)` – Name of the group.
- `type` `(string: "internal")` - Type of the group, `internal` or `external`.
Defaults to `internal`.
- `metadata` `(key-value-map: {})` – Metadata to be associated with the
group.
- `policies` `(list of strings: [])` – Policies to be tied to the group.
- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as
group members.
- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as
group members.
### Sample payload
```json
{
"metadata": {
"hello": "everyone"
},
"policies": ["grouppolicy2", "grouppolicy3"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```
### Sample response
```json
{
"request_id": "b98b4a3d-a9f1-e151-11e1-ad91cfb08351",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece",
"name": "testgroupname"
},
"warnings": null
}
```
## Read group by name
This endpoint queries the group by its name.
| Method | Path |
| :----- | :--------------------------- |
| `GET` | `/identity/group/name/:name` |
### Parameters
- `name` `(string: <required>)` – Name of the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```
### Sample response
```json
{
"data": {
"alias": {},
"creation_time": "2018-09-19T22:02:04.395128091Z",
"id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece",
"last_update_time": "2018-09-19T22:02:04.395128091Z",
"member_entity_ids": [],
"member_group_ids": null,
"metadata": {
"foo": "bar"
},
"modify_index": 1,
"name": "testgroupname",
"parent_group_ids": null,
"policies": ["grouppolicy1", "grouppolicy2"],
"type": "internal"
}
}
```
## Delete group by name
This endpoint deletes a group, given its name.
| Method | Path |
| :------- | :--------------------------- |
| `DELETE` | `/identity/group/name/:name` |
### Parameters
- `name` `(string: <required>)` – Name of the group.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```
## List groups by name
This endpoint returns a list of available groups by their names.
| Method | Path |
| :----- | :------------------------------- |
| `LIST` | `/identity/group/name` |
| `GET` | `/identity/group/name?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/group/name
```
### Sample response
```json
{
"data": {
"keys": ["testgroupname"]
}
}
```

25
website/content/api-docs/secret/identity/index.mdx
View file

@ -1,25 +0,0 @@
---
layout: api
page_title: Identity - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Identity secrets engine.
---
> [!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.
# Identity secrets engine (API)
This is the API documentation for the Vault Identity secrets engine. For general
information about the usage and operation of the Identity secrets engine, please
see the [Vault Identity documentation](/vault/docs/secrets/identity).
## API sections
- [Entity](/vault/api-docs/secret/identity/entity)
- [Entity Alias](/vault/api-docs/secret/identity/entity-alias)
- [Group](/vault/api-docs/secret/identity/group)
- [Group Alias](/vault/api-docs/secret/identity/group-alias)
- [Identity Tokens](/vault/api-docs/secret/identity/tokens)
- [Lookup](/vault/api-docs/secret/identity/lookup)
- [OIDC Provider](/vault/api-docs/secret/identity/oidc-provider)
- [MFA](/vault/api-docs/secret/identity/mfa)

134
website/content/api-docs/secret/identity/lookup.mdx
View file

@ -1,134 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Lookup - HTTP API'
description: |-
This is the API documentation for entity and group lookups from identity
store.
---
> [!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.
## Lookup an entity
This endpoint looks up an entity based on the given criteria. The criteria can
be `name`, `id`, `alias_id`, or a combination of `alias_name` and
`alias_mount_accessor`.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/identity/lookup/entity` |
### Parameters
- `name` `(string: "")` – Name of the entity.
- `id` `(string: "")` - ID of the entity.
- `alias_id` `(string: "")` - ID of the alias.
- `alias_name` `(string: "")` - Name of the alias. This should be supplied in
conjunction with `alias_mount_accessor`.
- `alias_mount_accessor` `(string: "")` - Accessor of the mount to which the
alias belongs to. This should be supplied in conjunction with `alias_name`.
### Sample payload
```json
{
"id": "043fedec-967d-b2c9-d3af-0c467b04e1fd"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/lookup/entity
```
### Sample response
```json
{
"data": {
"aliases": [],
"creation_time": "2017-11-13T21:01:33.543497Z",
"direct_group_ids": [],
"group_ids": [],
"id": "043fedec-967d-b2c9-d3af-0c467b04e1fd",
"inherited_group_ids": [],
"last_update_time": "2017-11-13T21:01:33.543497Z",
"merged_entity_ids": null,
"metadata": null,
"name": "entity_43cc451b",
"policies": null
}
}
```
## Lookup a group
This endpoint looks up a group based on the given criteria. The criteria can
be `name`, `id`, `alias_id`, or a combination of `alias_name` and
`alias_mount_accessor`.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/identity/lookup/group` |
### Parameters
- `name` `(string: "")` – Name of the group.
- `id` `(string: "")` - ID of the group.
- `alias_id` `(string: "")` - ID of the alias.
- `alias_name` `(string: "")` - Name of the alias. This should be supplied in
conjunction with `alias_mount_accessor`.
- `alias_mount_accessor` `(string: "")` - Accessor of the mount to which the
alias belongs to. This should be supplied in conjunction with `alias_name`.
### Sample payload
```json
{
"id": "70a4bdef-9da3-4460-b524-bb08542eef25"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/lookup/group
```
### Sample response
```json
{
"data": {
"alias": {},
"creation_time": "2017-11-13T21:06:44.475587Z",
"id": "70a4bdef-9da3-4460-b524-bb08542eef25",
"last_update_time": "2017-11-13T21:06:44.475587Z",
"member_entity_ids": [],
"member_group_ids": null,
"metadata": null,
"modify_index": 1,
"name": "group_eaf2aab1",
"policies": null,
"type": "internal"
}
}
```

183
website/content/api-docs/secret/identity/mfa/duo.mdx
View file

@ -1,183 +0,0 @@
---
layout: api
page_title: /identity/mfa/method/duo - HTTP API
description: >-
The '/identity/mfa/method/duo' endpoint focuses on managing Duo MFA behaviors in Vault.
---
> [!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.
## Create Duo MFA method
This endpoint creates a new MFA method of type Duo.
| Method | Path |
|:-------|:---------------------------|
| `POST` | `/identity/mfa/method/duo` |
### Parameters
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A template string for mapping Identity names to MFA methods. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}"`. If blank, the Entity's Name field is used as-is.
- `secret_key` `(string: <required>)` - Secret key for Duo.
- `integration_key` `(string: <required>)` - Integration key for Duo.
- `api_hostname` `(string: <required>)` - API hostname for Duo.
- `push_info` `(string)` - Push information for Duo.
- `use_passcode` `(bool: false)` - If true, the user is reminded to use the passcode upon MFA validation.
### Sample payload
```json
{
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"secret_key": "BIACEUEAXI20BNWTEYXT",
"integration_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz",
"api_hostname": "api-2b5c39f5.duosecurity.com",
"method_name": "ns1_duo"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/duo
```
### Sample response
```json
{
"data": {
"method_id": "0888fd69-4ea2-91d7-415e-c4bba548529b"
}
}
```
## Update Duo MFA method
This endpoint updates the configuration of an MFA method of type Duo.
| Method | Path |
|:-------|:--------------------------------------|
| `POST` | `/identity/mfa/method/duo/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- and all of the parameters documented under the preceding "Create" endpoint.
### Sample payload
Identical to the preceding "Create" endpoint.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
```
## Read Duo MFA method
This endpoint queries the MFA configuration of Duo type for a given method
ID.
| Method | Path |
|:-------|:--------------------------------------|
| `GET` | `/identity/mfa/method/duo/:method_id` |
### Parameters
- `id` `(string: <required>)` – UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
```
### Sample response
```json
{
"data": {
"api_hostname": "api-2b5c39f5.duosecurity.com",
"id": "4194659f-139b-400b-b5dd-86bfb726759d",
"integration_key": "BIACEUEAXI20BNWTEYXT",
"pushinfo": "",
"secret_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz",
"type": "duo",
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"use_passcode": false
}
}
```
## Delete Duo MFA method
This endpoint deletes a Duo MFA method. MFA methods can only be deleted if they're not currently in use
by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement).
| Method | Path |
|:---------|:--------------------------------------|
| `DELETE` | `/identity/mfa/method/duo/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
```
## List Duo MFA methods
This endpoint lists Duo MFA methods that are visible in the current namespace or in parent namespaces.
| Method | Path |
|:-------|:---------------------------|
| `LIST` | `/identity/mfa/method/duo` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/duo
```
### Sample response
```json
{
"data": {
"keys": [
"4194659f-139b-400b-b5dd-86bfb726759d"
]
}
}
```

30
website/content/api-docs/secret/identity/mfa/index.mdx
View file

@ -1,30 +0,0 @@
---
layout: api
page_title: /identity/mfa - HTTP API
description: >-
The '/identity/mfa' endpoint focuses on managing login MFA behaviors in Vault.
---
> [!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.
# `/identity/mfa`
## Supported MFA types.
- [TOTP](/vault/api-docs/secret/identity/mfa/totp)
- [Okta](/vault/api-docs/secret/identity/mfa/okta)
- [Duo](/vault/api-docs/secret/identity/mfa/duo)
- [PingID](/vault/api-docs/secret/identity/mfa/pingid)
## Other
- [Login Enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement)
- [MFA Validate](/vault/api-docs/system/mfa/validate)
While the above endpoints are available in all editions of Vault,
they are namespace aware. MFA methods and login enforcements created in one namespace are separate from other
namespaces. In the community version of Vault, everything operates in the root namespace.

156
website/content/api-docs/secret/identity/mfa/login-enforcement.mdx
View file

@ -1,156 +0,0 @@
---
layout: api
page_title: /identity/mfa/login-enforcement - HTTP API
description: >-
The '/identity/mfa/login-enforcement' endpoint focuses on specifying which MFA methods should be used
when logging in.
---
> [!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.
## Create a login enforcement
This endpoint creates or updates a login enforcement that specifies which MFA methods should be used when logging into
Vault. If there are multiple login enforcements, each one needs to be satisfied before a login attempt succeeds.
| Method | Path |
| :----- |:----------------------------------------|
| `POST` | `/identity/mfa/login-enforcement/:name` |
### Parameters
- `name` `(string: <required>)` - Name for this login enforcement configuration.
- `mfa_method_ids` `([]string: <required>)` - Array of MFA method UUIDs to use. These will be ORed together, meaning
if several IDs are specified, any one of them is sufficient to login.
- `auth_method_accessors` `([]string: [])` - Array of auth mount accessor IDs. If present, only auth methods
corresponding to the given accessors are checked during login.
- `auth_method_types` `([]string: [])` - Array of auth method types. If present, only auth methods
corresponding to the given types are checked during login.
- `identity_group_ids` `([]string: [])` - Array of identity group IDs. If present, only entities belonging
to one of the given groups are checked during login. Note that these IDs can be from the current namespace or
a child namespace.
- `identity_entity_ids` `([]string: [])` - Array of identity entity IDs. If present, only entities with the given
IDs are checked during login. Note that these IDs can be from the current namespace or a child namespace.
Note that while none of `auth_method_accessors`, `auth_method_types`, `identity_group_ids`, or `identity_entity_ids` is
individually required, at least one of those four fields must be present to create a login enforcement.
### Sample payload
```json
{
"mfa_method_ids": ["134f7ce9-feae-4c6c-9ed7-ab3e413dbfce"],
"auth_method_accessors": ["auth_userpass_337fdb6a"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo
```
## Read login enforcement
This endpoint reads the login enforcement configuration for a given name.
| Method | Path |
| :----- |:----------------------------------------|
| `GET` | `/identity/mfa/login-enforcement/:name` |
### Parameters
- `name` `(string: <required>)` – Name of the login enforcement.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo
```
### Sample response
```json
{
"data": {
"auth_method_accessors": [
"auth_userpass_337fdb6a"
],
"auth_method_types": [],
"id": "24167a6c-759a-c596-6d48-391c89c4befc",
"identity_entity_ids": [],
"identity_group_ids": [],
"mfa_method_ids": [
"c1372abf-bf64-1f26-c2a4-cbcfa135b775"
],
"name": "foo",
"namespace_id": "root"
}
}
```
## Delete login enforcement
This endpoint deletes a login enforcement configuration by the given name.
| Method | Path |
| :------- |:----------------------------------------|
| `DELETE` | `/identity/mfa/login-enforcement/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the login enforcement.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo
```
## List login enforcements
This endpoint lists login enforcements that are visible in the current namespace or in parent namespaces.
| Method | Path |
|:-------|:----------------------------------|
| `LIST` | `/identity/mfa/login-enforcement` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/login-enforcement
```
### Sample response
```json
{
"data": {
"keys": [
"foo"
]
}
}
```

177
website/content/api-docs/secret/identity/mfa/okta.mdx
View file

@ -1,177 +0,0 @@
---
layout: api
page_title: /identity/mfa/method/okta - HTTP API
description: >-
The '/identity/mfa/method/okta' endpoint focuses on managing Okta MFA behaviors in Vault.
---
> [!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.
## Create okta MFA method
This endpoint creates a new MFA method of type Okta.
| Method | Path |
|:-------|:----------------------------|
| `POST` | `/identity/mfa/method/okta` |
### Parameters
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is.
- `org_name` `(string: <required>)` - Name of the organization to be used in the Okta API.
- `api_token` `(string: <required>)` - Okta API key.
- `base_url` `(string)` - If set, will be used as the base domain for API requests. Examples are okta.com, oktapreview.com, and okta-emea.com.
- `primary_email` `(bool: false)` - If set, the username will only match the primary email for the account.
### Sample payload
```json
{
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"org_name": "dev-262778",
"api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/okta
```
### Sample response
```json
{
"data": {
"method_id": "0888fd69-4ea2-91d7-415e-c4bba548529b"
}
}
```
## Update okta MFA method
This endpoint updates the configuration of an MFA method of type Okta.
| Method | Path |
|:-------|:---------------------------------------|
| `POST` | `/identity/mfa/method/okta/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- and all of the parameters documented under the preceding "Create" endpoint.
### Sample payload
Identical to the preceding "Create" endpoint.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
```
## Read okta MFA method
This endpoint queries the MFA configuration of Okta type for a given method
name.
| Method | Path |
|:-------|:---------------------------------------|
| `GET` | `/identity/mfa/method/okta/:method_id` |
### Parameters
- `method_id` `(string: <required>)` – UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
```
### Sample response
```json
{
"data": {
"api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC",
"id": "1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc",
"name": "my_okta",
"org_name": "dev-262778",
"type": "okta",
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}"
}
}
```
## Delete okta MFA method
This endpoint deletes a Okta MFA method. The MFA methods can only be deleted if they're not currently in use
by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement).
| Method | Path |
|:---------|:---------------------------------------|
| `DELETE` | `/identity/mfa/method/okta/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
```
## List okta MFA methods
This endpoint lists Okta MFA methods that are visible in the current namespace or in parent namespaces.
| Method | Path |
|:-------|:----------------------------|
| `LIST` | `/identity/mfa/method/okta` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/okta
```
### Sample response
```json
{
"data": {
"keys": [
"1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc"
]
}
}
```

161
website/content/api-docs/secret/identity/mfa/pingid.mdx
View file

@ -1,161 +0,0 @@
---
layout: api
page_title: /identity/mfa/method/pingid - HTTP API
description: >-
The '/identity/mfa/method/pingid' endpoint focuses on managing PingID MFA behaviors in Vault.
---
> [!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.
## Create PingID MFA method
This endpoint creates an MFA method of type PingID.
| Method | Path |
|:-------|:------------------------------|
| `POST` | `/identity/mfa/method/pingid` |
### Parameters
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A template string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is.
- `settings_file_base64` `(string: <required>)` - A base64-encoded third-party settings file retrieved from PingID's configuration page.
### Sample payload
```json
{
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"settings_file_base64": "AA8owj3..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid
```
## Update PingID MFA method
This endpoint updates the configuration of an MFA method of type PingID.
| Method | Path |
|:-------|:-----------------------------------------|
| `POST` | `/identity/mfa/method/pingid/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- and all of the parameters documented under the preceding "Create" endpoint.
### Sample payload
Identical to the preceding "Create" endpoint.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
```
## Read PingID MFA method
This endpoint queries the MFA configuration of PingID type for a given method
name.
| Method | Path |
|:-------|:----------------------------------|
| `GET` | `/identity/mfa/method/pingid/:id` |
### Parameters
- `id` `(string: <required>)` – UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
```
### Sample response
```json
{
"data": {
"use_signature": true,
"idp_url": "https://idpxnyl3m.pingidentity.com/pingid",
"admin_url": "https://idpxnyl3m.pingidentity.com/pingid",
"authenticator_url": "https://authenticator.pingone.com/pingid/ppm",
"id": "f8381105-67f0-4105-8662-4b07ae5c1233",
"org_alias": "181459b0-9fb1-4938-8c86...",
"type": "pingid",
}
}
```
## Delete PingID MFA method
This endpoint deletes a PingID MFA method. MFA methods can only be deleted if they're not currently in use
by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement).
| Method | Path |
|:---------|:----------------------------------|
| `DELETE` | `/identity/mfa/method/pingid/:id` |
### Parameters
- `id` `(string: <required>)` - UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
```
## List PingID MFA methods
This endpoint lists PingID MFA methods that are visible in the current namespace or in parent namespaces.
| Method | Path |
|:-------|:------------------------------|
| `LIST` | `/identity/mfa/method/pingid` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid
```
### Sample response
```json
{
"data": {
"keys": [
"f8381105-67f0-4105-8662-4b07ae5c1233"
]
}
}
```

305
website/content/api-docs/secret/identity/mfa/totp.mdx
View file

@ -1,305 +0,0 @@
---
layout: api
page_title: /identity/mfa/method/totp - HTTP API
description: >-
The '/identity/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in Vault.
---
> [!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.
## Create TOTP MFA method
This endpoint creates an MFA method of type TOTP.
| Method | Path |
|:-------|:----------------------------|
| `POST` | `/identity/mfa/method/totp` |
### Parameters
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `issuer` `(string: <required>)` - The name of the key's issuing organization.
- `period` `(int or duration format string: 30)` - The length of time used to generate a counter for the TOTP token calculation.
- `key_size` `(int: 20)` – Specifies the size in bytes of the generated key.
- `qr_size` `(int: 200)` - The pixel size of the generated square QR code.
- `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".
- `digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8.
- `skew` `(int: 1)` - The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1.
- `max_validation_attempts` `(int: 5)` - The maximum number of consecutive failed validation attempts.
### Sample payload
```json
{
"issuer": "vault"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/totp
```
## Update TOTP MFA method
This endpoint updates the configuration of an MFA method of type TOTP.
| Method | Path |
|:-------|:---------------------------------------|
| `POST` | `/identity/mfa/method/totp/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- and all of the parameters documented under the preceding "Create" endpoint.
### Sample payload
Identical to the preceding "Create" endpoint.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/1f36d4cf-52c9-475d-a5cd-49c573c54e55
```
## Read TOTP MFA method
This endpoint queries the MFA configuration of TOTP type for a given method
ID.
| Method | Path |
|:-------|:---------------------------------------|
| `GET` | `/identity/mfa/method/totp/:method_id` |
### Parameters
- `method_id` `(string: <required>)` – UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
```
### Sample response
```json
{
"data": {
"algorithm": "SHA1",
"digits": 6,
"id": "4c6b1968-b385-4c46-ac5e-9b74e7b206be",
"issuer": "vault",
"key_size": 20,
"period": 30,
"qr_size": 200,
"skew": 1,
"type": "totp",
"namespace": ""
}
}
```
## Delete TOTP MFA method
This endpoint deletes a TOTP MFA method. MFA methods can only be deleted if they're not currently in use
by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement).
| Method | Path |
|:---------|:---------------------------------------|
| `DELETE` | `/identity/mfa/method/totp/:method_id` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
```
## List TOTP MFA methods
This endpoint lists TOTP MFA methods that are visible in the current namespace or in parent namespaces.
| Method | Path |
|:-------|:----------------------------|
| `LIST` | `/identity/mfa/method/totp` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/totp
```
### Sample response
```json
{
"data": {
"keys": [
"1f36d4cf-52c9-475d-a5cd-49c573c54e55",
"4c6b1968-b385-4c46-ac5e-9b74e7b206be"
]
}
}
```
## Generate a TOTP MFA secret
This endpoint generates an MFA secret in the entity of the calling token, if it
doesn't exist already, using the configuration stored under the given MFA
method ID.
| Method | Path |
|:-------|:-------------------------------------|
| `POST` | `/identity/mfa/method/totp/generate` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
### Sample payload
```json
{
"method_id": "1f36d4cf-52c9-475d-a5cd-49c573c54e55"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/generate
```
### Sample response
```json
{
"data": {
"barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGc0lEQVR4nOyd244bOQxEZxbz/7+cRQI4sLWiyCLlTU1wzkMAu1uXTIGSxUv3148fH2DEP396AvDK189/Pj97jR/W9Wi/fs7uz/pZya5H92dk40fzjeY1+XtiIWYgiBkIYsbX84dba7O6B0z3hmgPqO5Z6/WsH3VvynjuDwsxA0HMQBAzvnZfZueI6Pvs93r2+z6ax7qWZ+2zPSP7PutfPW8of08sxAwEMQNBzNjuISqRLyc7X6jnkex8UPVBqXtJxk2PORZiBoKYgSBmXNlDsriIeq6J+umeG1RfVjav7L4JWIgZCGIGgpix3UO6a6MaU4/OD9Fnda2P2qnxl2ge1fbKOFiIGQhiBoKY8bKHdH052V5Q3VPUz9n42XhR++zzStWXVgELMQNBzEAQM37tIbd9MtX4Qvc8EI13q32210Sfb8wHCzEDQcxAEDM+f6532e/86nmiPYk31X2sZP1Pz0PVGP+pPRZiBoKYgSBmbPeQ/9xUvP6geg7p9leNj3RrH7v1K+reRm7vNwBBzEAQM471IVmt3oN31V9E93Xr3KNx1BrD7t+jMl8sxAwEMQNBzDjm9lZj5d04gZoLHPX3rjjFu3J5T/8/LMQMBDEDQcyQ6kPUHNsH1TU+Gi/qr+rLmo6zfq6eTzr9YiFmIIgZCGLG5/M69y5fzfr9Ol613bQ/NaYe9bui5gKczmNYiBkIYgaCmHF85mK01t2KO2Q1h9l43dzgbhxG7b+zZ2EhZiCIGQhiRuvZ77dygNVY+3q9es5Qv1+vT2sIlb0OCzEDQcxAEDMkX1bXN7S2z8brxl2q40b3rXR9bxn4sr4RCGIGgpjxUh8S0a2feFdNYrd/Ndad9Xsrpv/cHgsxA0HMQBAzPk/reXdN7fqA3ln/PZnndE9SxsFCzEAQMxDEjJd4iJqrqtYiPlBr9qZE81znk7V/F8TUjUEQMxDEjO1ze9U1PqtFzO5X87VW1H6i+XXqyneQl/UXgSBmIIgZpdzebgxdPWdMfVnr/dHn23XsWb18VpP4DBZiBoKYgSBmbPOyukzr2Lvnlu781FzkaF7deezAQsxAEDMQxIxjTP33TcN8JpXqOOp9qg8tm586n8qehYWYgSBmIIgZrfcYZvGPW2tztZ0aj8nGzb7Prnfr5z+wED8QxAwEMaP0PvVpzV63zru6pld//6t7SvRZzXmO5rPrBwsxA0HMQBAzpGeddH08WT/VNTv6vZ/NJxp/Wh8S9ZvN5/T/x0LMQBAzEMSMY0y9mpdV3YPU+pNsnGm+1v9dyxhBjaExCGIGgpixPYdUzwUdf/8JNV+qu3dE/aj9Z/Un0XzWcTiHGIMgZiCIGaX3qf+++fLe0f0dP83FVfO0VNS9jXOIMQhiBoKY8esc0vUBqb4ttY49Q13js/uzPKsuSr4XFmIGgpiBIGaM8rKmz0bJxo36nZ5Xov6zcbvnFqWWEQsxA0HMQBAzSs9cXKneH8ULpnUV0/lle0Y3DqOOv2uPhZiBIGYgiBnbOvVunfdKNyf2to9L9UV1Y/Tr/ep5iXiIIQhiBoKYcczLys4P1b2lGwNf23dr99Q8rqnvrOvr+sBC/EAQMxDEjG1M/UHXFxWhxAUq31evd5nmjWU+MvKyvgEIYgaCmLF9F+7Ul7TSrbdQzw/qeOv9K7f+v0o7LMQMBDEDQcw4vj8kYlpf3vUFZe2jeVbbVX1Y1fE6eyAWYgaCmIEgZmyfdVL9XT7NAb5F9xyh7n3Tc1IlToKFmIEgZiCIGaV3UHXrv6P23fyubj1K1l80zwg17yq6vhsfCzE DQcxAEDOOz+2troUZaq1hNP40lr/eP61TicbP5nO6joWYgSBmIIgZx7ysiNu+ruj6dB5q7D4ii5Oo82EP+UYgiBkIYob0/pCV2/Uda7/TunX1PJHNq9qvGvN/HgcLMQNBzEAQM1p5WdM6kI mv5zReNo9uvtet+WTz+sBC/EAQMxDEjO0zF99dA9it+6jOM7qe+dKqde7V/qP5nP5eWIgZCGIGgpix3UNUbsXkq/Xd2Thd35zqE5v66Hb9YCFmIIgZCGLGlT3kwS1fUbcGsVq3HvUXnY/U+ ExEZW/DQsxAEDMQxIzS+0Mybq3REd1c3ur5qBs7z/a4zjNWsBAzEMQMBDHjZQ+Z+oAeqGv42o9aq5j1m5HN51ZdfWX+WIgZCGIGgpixfX8I/DmwEDP+DQAA//9kwGH4xZewMgAAAABJRU5E rkJggg==",
"url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=XVE7TOZWJVEWQOATOD7 U53IEAJG72Z2I"
}
}
```
## Administratively generate a TOTP MFA secret
This endpoint can be used to generate a TOTP MFA secret. Unlike the `generate`
API which stores the generated secret on the entity ID of the calling token,
the `admin-generate` API stores the generated secret on the given entity ID.
| Method | Path |
|:-------|:-------------------------------------------|
| `POST` | `/identity/mfa/method/totp/admin-generate` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- `entity_id` `(string: <required>)` - Entity ID on which the generated secret
needs to get stored.
### Sample payload
```json
{
"method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4",
"entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-generate
```
### Sample response
```json
{
"data": {
"barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGZElEQVR4nOyd7W4jNwxFkyLv/8pbpMAAHnUo8pJyc1Oc82OB2KOP9QVFSyTlrz9/PsCIv356AnDn6/ufz89e48i6ov6u59f319ezfqtWnf2/snHX19XnVL7bYyFmIIgZCGLG5/e61V2b37WWXkRr9+lxonEvqv1XfeHK6/NYiBkIYgaCmPH19GK2j4ieX9/P9h0R2T6l+pzqYzKfmM0zQvk8sRAzEMQMBDHj0YdMqa6Z1TOvyDdF/VTPnqLnVzIfePLEHAsxA0HMQBAz3uJDqvuVbO1Vv/934yzReNV4ykmwEDMQxAwEMePRh5xeG6fxjNXnVM+Y1HHVM7Tq56R8nliIGQhiBoKYcfMhp2LT6hp7UY2hV8dTY/KZT1N9SufzxELMQBAzEMSMf3zI6X2HembUXbuz8dT9g+qLIiafJxZiBoKYgSBm3OpDunlMartTubrdeEUWI1dzAqa5wK9gIWYgiBkIYsaReIi6P1jbqd/7qznDqm9SfcKJs6sVLMQMBDEDQcz43K3z3fqLaf336fiFymQf8dRe8aVYiBkIYgaCmHHzIdW8pGo8QT1rOuULTvkc9a6TqD+lTgULMQNBzEAQMx7jIRdqjV7ULvpbrReJxl/nodYodseLxu/GWz6wED8QxAwEMeN2X9ZK9/4neRLDNfrUc919yPp8t/8PLMQPBDEDQcyQ6tTVO0JWqvGT6PWu75jub6L+T/kg4iHGIIgZCGLGKB5yKn5SpVuDWKXrI0/4jgssxAwEMQNBzNieZWV0v/erZ0Knxp3OYxoXqoyPhZiBIGYgiBmPub1q7m7G6fiB2n+3niSbZwT7kP8RCGIGgpjxeF9W5iPU8/+ofUY1r6q6ZkfzmtbJV2skozw04iHGIIgZCGKGlJeVvZ61V+MX07OiqJ9oftE41fGm9TD4EEMQxAwEMaN010lW1zGNoVfX+OrZl/rcfx0P2c0XCzEDQcxAEDMe87K68YBubH7tdxonmcb0q+2qZ2DK/gkLMQNBzEAQM2516lXUs6GIbA3v+qruPinrX/Ud0Xx288JCzEAQMxDEjG2NYXf/odztsXuuEoOu9BO93933RONm86n0h4WYgSBmIIgZt9+gqtaDq7m3K2rObnc+UT/Z36f2MZ28MCzEDAQxA0HMaJ1lTevBo/5OxRsysv1O9Fx1nO4Z3QcW4geCmIEgZki/H1Klu+Z369PVeVXHexfEQ34RCGIGgpjxWGN40c1VXdtXaxW79SLTOvqonVpDqdavkNv7C0AQMxDEjNK9vdP4gFq3ntV1Z+NEf099ZEZ1vrv+sBAzEMQMBDFjW2PYjT9U4xqqT1D7/ak4j5rn9QoWYgaCmIEgZpTu7e2u5Vk/4aQO3XFSHUc9s1rnNfVdr/1hIWYgiBkIYsZtH6LGA9Z20d8Z3fuq1HyqUznC1fZVX0c8xBgEMQNBzNje2xvxrlzYan1K1H82fjXOUfU12XzW5yufBxZiBoKYgSBmSL+FezE9s1lR9yHq2VvUT7fefOpjd58fFmIGgpiBIGZId52sr6u5u9M7RtTn1Hmr8ZzqnSvK2R4WYgaCmIEgZmzjIdHr3Rzfi278I3pdvStFrWVUfU52d8quPRZiBoKYgSBmbOvU//Xwobr1U7FpNV8qatetm4+onvU9jYuFmIEgZiCIGbf7srLv1d01vLsWqzmzapymeyaWfQ5qXtsrWIgZCGIGgphR+g2q9f0V9Y6SartsXtP8qOmZWDTe5AwMCzEDQcxAEDMeY+rVfUj0fLddN9Y+3feodfPd+pnKvLAQMxDEDAQxY1unPo11q+2i8adxCXV+an/qfHbzwELMQBAzEMQMKaYediL6FDVmruaBTWsU1bMwdT67/zcWYgaCmIEgZrR+g+piPata18Tu9/Zurq5aTxLNV833qs6nMg8sxAwEMQNBzHisD8lQ6y3W/qt3kpyuS8/ez3xiNL/qfMjL+oUgiBkIYkYppn7R9THd56s5tBGn60myfcSJ3GMsxAwEMQNBzGjdlxXRja1068mj9tla3c3DysaLxon+fgILMQNBzEAQM476kG5c5aJ7BnS6bqX6+jS/jLysXwCCmIEgZmx/x7DK6btCurF31WdMawPfkXOMhZiBIGYgiBmPvx+iUo2RV/vp3llSpZuXpfqgbNwnsBAzEMQMBDHjSH0InAMLMePvAAAA//8x2VnbmmL6HQAAAABJRU5ErkJggg==",
"url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U"
}
}
```
### Administratively destroy TOTP MFA secret
This endpoint deletes a TOTP MFA secret from the given entity ID.
To overwrite a secret on the entity,
explicitly deleting the secret first is required. This API can be used to delete the secret
and the `generate` or `admin-generate` APIs should be used to regenerate a new
secret.
| Method | Path |
|:-------|:------------------------------------------|
| `POST` | `/identity/mfa/method/totp/admin-destroy` |
### Parameters
- `method_id` `(string: <required>)` - UUID of the MFA method.
- `entity_id` `(string: <required>)` - Entity ID from which the MFA secret
should be removed.
### Sample payload
```json
{
"method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4",
"entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-destroy
```

837
website/content/api-docs/secret/identity/oidc-provider.mdx
View file

@ -1,837 +0,0 @@
---
layout: api
page_title: 'OIDC Identity Provider'
description: >-
This is the API documentation for configuring and managing OIDC providers with Vault.
---
> [!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.
## Create or update a provider
This endpoint creates or updates a Provider.
| Method | Path |
| :----- | :----------------- |
| `POST` | `identity/oidc/provider/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the provider. This parameter is specified as part of the URL.
- `issuer` `(string: <optional>)` - Specifies what will be used as the `scheme://host:port` component for the `iss` claim of ID tokens. This defaults to a URL with
Vault's `api_addr` as the `scheme://host:port` component and `/v1/:namespace/identity/oidc/provider/:name` as the path
component. If provided explicitly, it must point to a Vault instance that is network reachable by clients for ID token validation.
- `allowed_client_ids` `([]string: <optional>)` – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If `"*"` is provided, all clients are allowed.
- `scopes_supported` `([]string: <optional>)` – The scopes available for requesting on the provider.
### Sample payload
```json
{
"allowed_client_ids": ["*"],
"scopes_supported": ["test-scope"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider
```
## Read provider by name
This endpoint queries the OIDC provider by its name.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/identity/oidc/provider/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the provider.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider
```
### Sample response
```json
{
"data": {
"allowed_client_ids":["*"],
"issuer":"",
"scopes_supported":["test-scope"]
}
}
```
## List providers
This endpoint returns a list of all OIDC providers.
| Method | Path |
| :----- | :------------------------------ |
| `LIST` | `/identity/oidc/provider` |
### Query parameters
- `allowed_client_id` `(string: <optional>)` – Filters the list of OIDC providers to those
that allow the given client ID in their set of [allowed_client_ids](/vault/api-docs/secret/identity/oidc-provider#allowed_client_ids).
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/provider
```
### Sample response
```json
{
"data": {
"key_info": {
"default": {
"allowed_client_ids": [
"*"
],
"issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default",
"scopes_supported": []
}
},
"keys": [
"default"
]
}
}
```
## Delete provider by name
This endpoint deletes an OIDC provider.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/identity/oidc/provider/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the provider.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider
```
## Create or update a scope
This endpoint creates or updates a scope.
| Method | Path |
| :----- | :----------------- |
| `POST` | `identity/oidc/scope/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the scope. This parameter is specified as part of the URL. The `openid` scope name is reserved.
- `template` `(string: <optional>)` - The [JSON template](/vault/docs/concepts/oidc-provider#scopes)
string for the scope. This may be provided as escaped JSON or base64 encoded JSON.
- `description` `(string: <optional>)` – A description of the scope.
### Sample payload
```json
{
"template":"{ \"groups\": {{identity.entity.groups.names}} }",
"description":"A simple scope example."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope
```
## Read scope by name
This endpoint queries a scope by its name.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/identity/oidc/scope/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the scope.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope
```
### Sample response
```json
{
"data": {
"description":"A simple scope example.",
"template":"{ \"groups\": {{identity.entity.groups.names}} }"
}
}
```
## List scopes
This endpoint returns a list of all configured scopes.
| Method | Path |
| :----- | :------------------------------ |
| `LIST` | `/identity/oidc/scope` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/scope
```
### Sample response
```json
{
"data": {
"keys":[
"test-scope"
]
}
}
```
## Delete scope by name
This endpoint deletes a scope.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/identity/oidc/scope/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the scope.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope
```
## Create or update a client
This endpoint creates or updates a client.
| Method | Path |
| :----- | :----------------- |
| `POST` | `identity/oidc/client/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the client. This parameter is specified as part of the URL.
- `key` `(string: "default")` – A reference to a [named key](/vault/api-docs/secret/identity/tokens#create-a-named-key)
resource. This key will be used to sign ID tokens for the client. This cannot be modified
after creation. If not supplied, defaults to the built-in [default key](/vault/docs/concepts/oidc-provider#keys).
- `redirect_uris` `([]string: <optional>)` - Redirection URI values used by the client. One of these values
must exactly match the `redirect_uri` parameter value used in each [authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
- `assignments` `([]string: <optional>)` – A list of assignment resources associated with
the client. Client assignments limit the Vault entities and groups that are allowed to
authenticate through the client. By default, no Vault entities are allowed. To allow all
Vault entities to authenticate through the client, supply the built-in
[allow_all](/vault/docs/concepts/oidc-provider#assignments) assignment.
- `client_type` `(string: "confidential")` – The [client type](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1)
based on its ability to maintain confidentiality of credentials. This cannot be modified
after creation. The following list details the differences between confidential and public
clients in Vault:
- `confidential`
- Capable of maintaining the confidentiality of its credentials
- Has a client secret
- Uses the `client_secret_basic` or `client_secret_post` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
- May use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636))
for the authorization code flow
- `public`
- Not capable of maintaining the confidentiality of its credentials
- Does not have a client secret
- Uses the `none` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
- Must use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636))
for the authorization code flow
- `id_token_ttl` `(int or duration: "24h")` – The time-to-live for ID tokens obtained by the client.
Accepts [duration format strings](/vault/docs/concepts/duration-format). The value should be less than the `verification_ttl`
on the key.
- `access_token_ttl` `(int or duration: "24h")` – The time-to-live for access tokens obtained by the client.
Accepts [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"key":"test-key",
"access_token_ttl":"30m",
"id_token_ttl":"1h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/client/test-client
```
## Read client by name
This endpoint queries a client by its name.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/identity/oidc/client/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the client.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/oidc/client/test-client
```
### Sample response
```json
{
"data":{
"access_token_ttl":1800,
"assignments":[],
"client_id":"014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb",
"client_secret":"hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM",
"client_type": "confidential",
"id_token_ttl":3600,
"key":"test-key",
"redirect_uris":[]
}
}
```
## List clients
This endpoint returns a list of all configured clients.
| Method | Path |
| :----- | :------------------------------ |
| `LIST` | `/identity/oidc/client` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/client
```
### Sample response
```json
{
"data": {
"key_info": {
"my-app": {
"access_token_ttl": 86400,
"assignments": [
"allow_all"
],
"client_id": "wGr981oYLJbcr4zrUriYxjxSc80JL7HW",
"client_type": "confidential",
"id_token_ttl": 86400,
"key": "default",
"redirect_uris": [
"http://localhost:5555/callback"
]
}
},
"keys": [
"my-app"
]
}
}
```
## Delete client by name
This endpoint deletes a client.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/identity/oidc/client/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the client.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/client/test-client
```
## Create or update an assignment
This endpoint creates or updates an assignment.
| Method | Path |
| :----- | :----------------- |
| `POST` | `identity/oidc/assignment/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the assignment. This parameter is specified as part of the URL.
- `entity_ids` `([]string: <optional>)` - A list of Vault [entity](/vault/docs/secrets/identity#entities-and-aliases) IDs.
- `group_ids` `([]string: <optional>)` – A list of Vault [group](/vault/docs/secrets/identity#identity-groups) IDs.
### Sample payload
```json
{
"group_ids":["262ca5b9-7b69-0a84-446a-303dc7d778af"],
"entity_ids":["b6094ac6-baf4-6520-b05a-2bd9f07c66da"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment
```
## Read assignment by name
This endpoint queries an assignment by its name.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/identity/oidc/assignment/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the assignment.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment
```
### Sample response
```json
{
"data":{
"entity_ids":[
"b6094ac6-baf4-6520-b05a-2bd9f07c66da"
],
"group_ids":[
"262ca5b9-7b69-0a84-446a-303dc7d778af"
]
}
}
```
## List assignments
This endpoint returns a list of all configured assignments.
| Method | Path |
| :----- | :------------------------------ |
| `LIST` | `/identity/oidc/assignment` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/assignment
```
### Sample response
```json
{
"data": {
"keys":[
"test-assignment"
]
}
}
```
## Delete assignment by name
This endpoint deletes an assignment.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/identity/oidc/assignment/:name` |
### Parameters
- `name` `(string: <required>)` – The name of the assignment.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment
```
## Read provider OpenID configuration
Returns OpenID Connect Metadata for a named OIDC provider. The response is a
compliant [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).
| Method | Path |
| :----- | :--------------------------------------------------------------- |
| `GET` | `/identity/oidc/provider/:name/.well-known/openid-configuration` |
### Parameters
- `name` `(string: <required>)` – The name of the provider. This parameter is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/openid-configuration
```
### Sample response
```json
{
"issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider",
"jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys",
"authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/test-provider/authorize",
"token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token",
"userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo",
"request_parameter_supported": false,
"request_uri_parameter_supported": false,
"id_token_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"EdDSA"
],
"response_types_supported": [
"code"
],
"scopes_supported": [
"openid"
],
"subject_types_supported": [
"public"
],
"grant_types_supported": [
"authorization_code"
],
"token_endpoint_auth_methods_supported": [
"client_secret_basic",
"client_secret_post",
"none"
],
"code_challenge_methods_supported": [
"plain",
"S256"
]
}
```
## Read provider public keys
Query this path to retrieve the public portion of keys for an OIDC provider.
Clients can use them to validate the authenticity of an identity token.
| Method | Path |
| :----- | :----------------------------------------------- |
| `GET` | `/identity/oidc/provider/:name/.well-known/keys` |
### Parameters
- `name` `(string: <required>)` – The name of the provider. This parameter is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys
```
### Sample response
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "ee7c0920-fdb9-5c1a-9c69-6dab710d1a09",
"alg": "RS256",
"n": "zdFjUV9lBw5nQPvTtwH-gzKgRG7iepvYbFoc2hNB0-inJL25oh-mvNW3GS8jPY5XHLsiWa_1TKKE99JrKQgane2C96soFeOvR7SozbCeH8_FpZelH1Pym1NV038j05Vp87uB9FeKPsy1PNOLPTs_Fp42JIAenly7ojYwPp1s61p9V0U9rOhtldY7GkXHLN9s8v3aJjxqrTS3Puhs9MFS7EgRrEDAc69uiLXCoYXKygjXddvJi6j446XxnO2eTRMGl1f2t04s_vDgVnFQgjQSKYWPbOMhf2slkeR47fqE3qqUDzINxauqMbkW-PlLP9IN0crR2uC07cG2os4RxN4YHw",
"e": "AQAB"
},
{
"use": "sig",
"kty": "RSA",
"kid": "6e468221-b7c2-9d2d-744d-33b7ae0357cb",
"alg": "RS256",
"n": "rMaucILJKiFg_lkCE8ZEV_8jiYdaVDjKkc-8XPBW8S34wIRl1EbsgCYfMHtJnIJ_3eUgOVorW5KVeN9C8W16LR3lhqRWS9y4qlt0AcWpOvsmxr5q5dS_QqgCjeftCKwJzUsMi5bMW8wKjRZdd-qLz6X1rVSZWX82G0So8nRBg9d3MNJbKcdIJrRbrxWkm8U9xMqRouzbyQ2Hsp2rRVgGh7yjEA6daI5Ao8UsPdBmlCM9oKZ1_Kje5JTfZKeHlT-58vn_ylCjMVlapLuUsDN6He2kPVyOzGbie297VOfjmB7QX0ah1f7Ni1UJFJYHrVK9wMfCLTltSFZBcQ9--FlVdQ",
"e": "AQAB"
}
]}
```
## Authorization endpoint
Provides the [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint)
for an OIDC provider. This allows OIDC clients to request an authorization code
to be used for the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).
| Method | Path |
| :---------- | :---------------------------------------- |
| `GET/POST` | `/identity/oidc/provider/:name/authorize` |
### Parameters
- `name` `(string: <required>)` - The name of the provider. This parameter is specified as part of the URL.
- `scope` `(string: <required>)` - A space-delimited list of scopes to be requested. The `openid` scope is required.
- `response_type` `(string: <required>)` - The OIDC authentication flow to be used. The following response types are supported: `code`.
- `client_id` `(string: <required>)` - The ID of the requesting client.
- `redirect_uri` `(string: <required>)` - The redirection URI to which the response will be sent.
- `state` `(string: <optional>)` - A value used to maintain state between the authentication request and client.
- `nonce` `(string: <optional>)` - A value that is returned in the ID token nonce claim. It is used to mitigate replay attacks, so we *strongly encourage* providing this optional parameter.
- `max_age` `(integer: <optional>)` - The allowable elapsed time in seconds since the last
time the end-user was actively authenticated.
- `code_challenge` `(string: <optional>)` - The [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
code challenge derived from the client's code verifier. Optional for `confidential` clients.
Required for `public` clients.
- `code_challenge_method` `(string: "plain")` - The method that was used to derive the
[PKCE](https://datatracker.ietf.org/doc/html/rfc7636) code challenge. The following
methods are supported: `S256`, `plain`.
### Sample request
```shell-session
$ curl \
--request GET \
--header "X-Vault-Token: ..." \
-G \
-d "response_type=code" \
-d "client_id=$CLIENT_ID" \
-d "state=af0ifjsldkj" \
-d "nonce=abcdefghijk" \
--data-urlencode "scope=openid" \
--data-urlencode "redirect_uri=http://127.0.0.1:8251/callback" \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/authorize
```
### Sample response
```json
{
"code": "BDSc9kVYljxND93YpveBuJtSvguM3AWe",
"state": "af0ifjsldkj"
}
```
## Token endpoint
Provides the [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint)
for an OIDC provider.
| Method | Path |
| :------ | :------------------------------------ |
| `POST` | `/identity/oidc/provider/:name/token` |
### Parameters
- `name` `(string: <required>)` - The name of the provider. This parameter is
specified as part of the URL.
- `code` `(string: <required>)` - The authorization code received from the
provider's authorization endpoint.
- `grant_type` `(string: <required>)` - The authorization grant type. The
following grant types are supported: `authorization_code`.
- `redirect_uri` `(string: <required>)` - The callback location where the
authorization request was sent. This must match the `redirect_uri` used when the
original authorization code was generated.
- `client_id` `(string: <optional>)` - The ID of the requesting client. This parameter
is required for `public` clients which do not have a client secret or `confidential`
clients using the `client_secret_post` client authentication method.
- `client_secret` `(string: <optional>)` - The secret of the requesting client. This
parameter is required for `confidential` clients using the `client_secret_post` client
authentication method.
- `code_verifier` `(string: <optional>)` - The code verifier associated with the given
`code`. Required for authorization codes that were granted using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
Required for `public` clients.
### Headers
- `Authorization: Basic` `(string: <optional>)` - An HTTP Basic authentication scheme header
including the `client_id` and `client_secret` as described in the [client_secret_basic](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
authentication method. This header is only required for `confidential` clients using
the `client_secret_basic` client authentication method.
### Sample request
```shell-session
$ BASIC_AUTH_CREDS=$(printf "%s:%s" "$CLIENT_ID" "$CLIENT_SECRET" | base64)
$ curl \
--request POST \
--header "Authorization: Basic $BASIC_AUTH_CREDS" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d "code=4RL50r78p8HsNJY0GVUNGfjLHnpkRf3N" \
-d "grant_type=authorization_code" \
-d "redirect_uri=http://127.0.0.1:8251/callback" \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token
```
### Sample response
```json
{
"access_token": "b.AAAAAQJEH5VXjfjUESCwySTKk2MS1MGVNc9oU-N2EyoLKVo9SYa-NnOWAXloYfrlO45UWC3R1PC5ZShl3JdmRJ0264julNnlBduSNXJkYjgCQsFQwXTKHcjhqdNsmJNMWiPaHPn5NLSpNQVtzAxfHADt4r9rmX-UEG5seOWbmK_Z5WwS_4a8-wcVPB7FpOGzfBydP7yMxHu-3H1TWyQvYVr28XUfYxcBbdlzxhJn0yqkWItgmZ25xEOp7SW7Pg4tYB7AXfk",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzMjk5ZWVmLTllNDEtOGNiYS1kNWExLTZmZWM2NjIyODRjYyJ9.eyJhdF9oYXNoIjoiMUdlQlEzUFdtUjJ2ajZVU2swSW42USIsImF1ZCI6InpTSktMVmk0R1BYS1o3TTZzUUEwY3FNc05VaHNPYkVTIiwiY19oYXNoIjoiN09SOUszNmhNdllENzJkUkFLUHhNdyIsImNvbnRhY3QiOnsiZW1haWwiOiJ2YXVsdEBoYXNoaWNvcnAuY29tIiwicGhvbmVfbnVtYmVyIjoiMTIzLTQ1Ni03ODkwIn0sImV4cCI6MTYzMzEwNjI5NCwiZ3JvdXBzIjpbImVuZ2luZWVyaW5nIl0sImlhdCI6MTYzMzEwNDQ5NCwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL2lkZW50aXR5L29pZGMvcHJvdmlkZXIvbXktcHJvdmlkZXIiLCJuYW1lc3BhY2UiOiJyb290Iiwibm9uY2UiOiJhYmNkZWZnaGlqayIsInN1YiI6IjUwMDA3OTZlLTM2ZGYtMGQ4Yy02NDYwLTgxODUzZDliMjY2NyIsInVzZXJuYW1lIjoiZW5kLXVzZXIifQ.ehdLj6jnrJvltar1kkVSyNK48w2M5vkh5DTFJFZDqatnDWhQbbKGLZnVgd3wD6KPboXRaUwhGe4jDiTIiSoJaovOhsia77NKukym_ROLvGZw-LG7xaYkzJLnmEfeQhelLxWe0DHPROB7VXcFqBx8vX5hkuoVyqrB87vwiobK42pDPZ9MRsmbM2yzBC3wrnT7RQFtT4q2Bbyt9YIAHUaq9rU0PwJRoNISw6of1uQHo3_UzLdpwth7PEOEcI47OBGFA5vR_Gw3ocREfSrUWfCWOInAKCT43cImvg4Bts6qiZYfv9n-iNBq4AihGqq_VEF-hB1Hrprn7VgnEZ1VjUHaQQ",
"token_type": "Bearer"
}
```
## UserInfo endpoint
Provides the [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
for an OIDC provider. The UserInfo Endpoint is an OAuth 2.0 Protected
Resource that returns Claims about the authenticated End-User.
| Method | Path |
| :------ | :--------------------------------------- |
| `POST` | `/identity/oidc/provider/:name/userinfo` |
### Parameters
- `name` `(string: <required>)` - The name of the provider. This parameter is
specified as part of the URL.
### Headers
- Access Token `(string: <required>)` - The access token provided by the
`Authorization: Bearer <access_token>` HTTP header acquired from the authorization
endpoint.
### Sample request
```shell-session
$ curl \
-X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo
```
### Sample response
```json
{
"contact": {
"email": "vault@hashicorp.com",
"phone_number": "123-456-7890"
},
"groups": [
"engineering"
],
"sub": "5000796e-36df-0d8c-6460-81853d9b2667",
"username": "end-user"}
```

567
website/content/api-docs/secret/identity/tokens.mdx
View file

@ -1,567 +0,0 @@
---
layout: api
page_title: 'Identity Secret Backend: Identity Tokens - HTTP API'
description: >-
This is the API documentation for configuring, acquiring, and validating vault
issued identity tokens.
---
> [!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.
## Configure the identity tokens backend
This endpoint updates configurations for OIDC-compliant identity tokens issued by Vault.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `identity/oidc/config` |
### Parameters
- `issuer` `(string: "")` – Issuer URL to be used in the iss claim of the token. If not set, Vault's api_addr will be used. The issuer is a case sensitive URL using the https scheme that contains scheme, host, and an optional port number.
### Sample payload
```json
{
"issuer": "https://example.com:1234"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/config
```
### Sample response
```json
{
"data": null,
"warnings": [
"If \"issuer\" is set explicitly, all tokens must be validated against that address, including those issued by secondary clusters. Setting issuer to \"\" will restore the default behavior of using the cluster's api_addr as the issuer."
]
}
```
## Read configurations for the identity tokens backend
This endpoint queries vault identity tokens configurations.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `identity/oidc/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/config
```
### Sample response
```json
{
"data": {
"issuer": "https://example.com:1234"
}
}
```
## Create a named key
This endpoint creates or updates a named key which is used by a role to sign tokens.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` – Name of the named key.
- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `allowed_client_ids` `(list: [])` - Array of role client ids allowed to use this key for signing. If empty, no roles are allowed. If "\*", all roles are allowed.
- `algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default), RS384, RS512, ES256, ES384, ES512, EdDSA.
### Sample payload
```json
{
"rotation_period": "12h",
"verification_ttl": 43200
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
## Read a named key
This endpoint queries a named key and returns its configurations.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` – Name of the key.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
### Sample response
```json
{
"data": {
"algorithm": "RS256",
"rotation_period": 43200,
"verification_ttl": 43200
}
}
```
## Delete a named key
This endpoint deletes a named key.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` – Name of the key.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
## List named keys
This endpoint will List all named keys.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `identity/oidc/key` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/key
```
### Sample response
```json
{
"data": {
"keys": ["named-key-001", "named-key-002"]
}
}
```
## Rotate a named key
This endpoint rotates a named key.
| Method | Path |
| :----- | :------------------------------- |
| `POST` | `identity/oidc/key/:name/rotate` |
### Parameters
- `name` `(string)` – Name of the key to be rotated.
- `verification_ttl` `(string: <optional>)` - Controls how long the public portion of the key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key.
### Sample payload
```json
{
"verification_ttl": 0
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate
```
## Create or update a role
Create or update a role. ID tokens are generated against a role and signed against a named key.
| Method | Path |
| :----- | :------------------------- |
| `POST` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` – Name of the role.
- `key` `(string)` – A configured named key, the key must already exist.
- `template` `(string: <optional>)` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format.
- `client_id` `(string: <optional>)` - Optional client ID. A random ID will be generated if left unset.
- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"key": "named-key-001",
"ttl": "12h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
## Read a role
This endpoint queries a role and returs its configuration.
| Method | Path |
| :----- | :------------------------- |
| `GET` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` – Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
### Sample response
```json
{
"data": {
"client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH",
"key": "named-key-001",
"template": "",
"ttl": 43200
}
}
```
## Delete a role
This endpoint deletes a role.
| Method | Path |
| :------- | :------------------------- |
| `DELETE` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` – Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
## List roles
This endpoint will list all signing keys.
| Method | Path |
| :----- | :------------------- |
| `LIST` | `identity/oidc/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/role
```
### Sample response
```json
{
"data": {
"keys": ["role-001", "role-002", "testrole"]
}
}
```
## Generate a signed ID token
Use this endpoint to generate a signed ID (OIDC) token.
| Method | Path |
| :----- | :-------------------------- |
| `GET` | `identity/oidc/token/:name` |
### Parameters
- `name` `(string: "")` – The name of the role against which to generate a signed ID token
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/token/role-001
```
### Sample response
```json
{
"data": {
"client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7",
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g",
"ttl": 86400
}
}
```
## Introspect a signed ID token
This endpoint can verify the authenticity and active state of a signed ID token.
| Method | Path |
| :----- | :------------------------- |
| `POST` | `identity/oidc/introspect` |
### Parameters
- `token` `(string)` – A signed OIDC compliant ID token
- `client_id` `(string: <optional>)` - Specifying the client ID additionally requires the token to contain a matching `aud` claim
### Sample payload
```json
{
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/introspect
```
### Sample response
```json
{
"active": true
}
```
## Read the OpenID configuration from an identity token issuer
Use the `.well-known` endpoint to retrieve an
[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse)
with a set of claims about the identity token issuer.
| Method | Path |
| :----- | :----------------------------------------------- |
| `GET` | `identity/oidc/.well-known/openid-configuration` |
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration
```
### Sample response
```json
{
"issuer": "https://example.com/v1/identity/oidc",
"jwks_uri": "https://example.com/v1/identity/oidc/.well-known/keys",
"response_types_supported": [
"id_token"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"EdDSA"
]
}
```
## Read identity token issuer's public JWKS
Query `identity/oidc/.well-known/keys` to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys
```
### Sample response
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "94178020-55b5-e18d-b32b-1010ba5a35b4",
"alg": "RS256",
"n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw",
"e": "AQAB"
}
]
}
```
## Read plugin identity token issuer's OpenID configuration <EnterpriseAlert product="vault" inline />
Use the `.well-known` endpoint to retrieve an
[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse)
with a set of claims about the plugin identity token issuer.
| Method | Path |
| :----- | :----------------------------------------------- |
| `GET` | `identity/oidc/plugins/.well-known/openid-configuration` |
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/plugins/.well-known/openid-configuration
```
### Sample response
```json
{
"issuer": "https://example.com/v1/identity/oidc/plugins",
"jwks_uri": "https://example.com/v1/identity/oidc/plugins/.well-known/keys",
"response_types_supported": [
"id_token"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"EdDSA"
]
}
```
## Read the public JWKS from a plugin identity token issuer <EnterpriseAlert product="vault" inline />
Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys
```
### Sample response
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "94178020-55b5-e18d-b32b-1010ba5a35b4",
"alg": "RS256",
"n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw",
"e": "AQAB"
}
]
}
```

20
website/content/api-docs/secret/index.mdx
View file

@ -1,20 +0,0 @@
---
layout: api
page_title: Secrets Engines - HTTP API
description: |-
Each secrets engine publishes its own set of API paths and methods. These
endpoints are documented in this section.
---
> [!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.
# Secrets engines
Each secrets engine publishes its own set of API paths and methods. These
endpoints are documented in this section. secrets engines are enabled at a path,
but the documentation will assume the default paths for simplicity. If you are
enabled at a different path, you should adjust your API calls accordingly.
For the API documentation for a specific secrets engine, please choose a secrets
engine from the navigation.

54
website/content/api-docs/secret/key-management/awskms.mdx
View file

@ -1,54 +0,0 @@
---
layout: api
page_title: AWS KMS - Key Management - Secrets Engines - HTTP API
description: The AWS KMS API documentation for the Key Management secrets engine.
---
> [!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.
# AWS KMS (API)
The Key Management secrets engine supports lifecycle management of keys in [AWS KMS](https://aws.amazon.com/kms/)
regions. This is accomplished by configuring a KMS provider resource with the `awskms` provider and
other provider-specific parameter values.
The following sections provide API documentation that is specific to AWS KMS.
## Create/Update KMS provider
This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
This is provided as part of the request URL.
- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
Vault. Must be set to `awskms`. Cannot be changed after creation.
- `key_collection` `(string: <required>)` – Refers to the name of an AWS
[region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/?p=ngi&loc=2).
Cannot be changed after creation.
- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
AWS KMS. Supplying values for this parameter is optional, as credentials may also be specified
as environment variables. Credentials provided to this parameter will take precedence over
credentials provided via environment variables.
- `access_key` `(string: <required>)` - The AWS access key ID. May also be specified
by the `AWS_ACCESS_KEY_ID` environment variable.
- `secret_key` `(string: <required>)` - The AWS secret access key. May also be specified
by the `AWS_SECRET_ACCESS_KEY` environment variable.
- `session_token` `(string: <optional>)` - The AWS session token. May also be specified
by the `AWS_SESSION_TOKEN` environment variable.
- `endpoint` `(string: <optional>)` - The KMS API endpoint to be used to make AWS KMS
requests. May also be specified by the `AWS_KMS_ENDPOINT` environment variable. This
is useful when connecting to KMS over a [VPC Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html).
If not set, the secrets engine will use the default API endpoint for the region.

52
website/content/api-docs/secret/key-management/azurekeyvault.mdx
View file

@ -1,52 +0,0 @@
---
layout: api
page_title: Azure Key Vault - Key Management - Secrets Engines - HTTP API
description: The Azure Key Vault API documentation for the Key Management secrets engine.
---
> [!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.
# Azure key Vault (API)
The Key Management secrets engine supports lifecycle management of keys in named
[Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/) instances.
This is accomplished by configuring a KMS provider resource with the `azurekeyvault`
provider and other provider-specific parameter values.
The following sections provide API documentation that is specific to Azure Key Vault.
## Create/Update KMS provider
This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
This is provided as part of the request URL.
- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
Vault. Must be set to `azurekeyvault`. Cannot be changed after creation.
- `key_collection` `(string: <required>)` – Refers to the name of an existing Azure Key Vault
instance. Cannot be changed after creation.
- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
Azure Key Vault. Supplying values for this parameter is optional, as credentials may also
be specified as environment variables. Environment variables will take precedence over
credentials provided via this parameter.
- `tenant_id` `(string: <required>)` - The tenant ID for the Azure Active Directory
organization. May also be specified by the `AZURE_TENANT_ID` environment variable.
- `client_id` `(string: <required or MSI>)` - The client ID for credentials to invoke the
Azure APIs. May also be specified by the `AZURE_CLIENT_ID` environment variable.
- `client_secret` `(string: <required or MSI>)` - The client secret for credentials to invoke
the Azure APIs. May also be specified by the `AZURE_CLIENT_SECRET` environment variable.
- `environment` `(string: "AzurePublicCloud")` - The Azure Cloud environment API endpoints to
use. May also be specified by the `AZURE_ENVIRONMENT` environment variable.

50
website/content/api-docs/secret/key-management/gcpkms.mdx
View file

@ -1,50 +0,0 @@
---
layout: api
page_title: GCP Cloud KMS - Key Management - Secrets Engines - HTTP API
description: The GCP Cloud KMS API documentation for the Key Management secrets engine.
---
> [!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.
# GCP Cloud KMS (API)
The Key Management secrets engine supports lifecycle management of keys in [GCP Cloud KMS](https://cloud.google.com/security-key-management)
[key rings](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). This is accomplished by
configuring a KMS provider resource with the `gcpckms` provider and other provider-specific parameter
values.
The following sections provide API documentation that is specific to GCP Cloud KMS.
## Create/Update KMS provider
This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
This is provided as part of the request URL.
- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
Vault. Must be set to `gcpckms`. Cannot be changed after creation.
- `key_collection` `(string: <required>)` – Refers to the
[resource ID](https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id)
of an existing GCP Cloud KMS [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings).
Cannot be changed after creation.
- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with GCP
Cloud KMS. Supplying values for this parameter is optional, as credentials may also be specified
as environment variables. See the [authentication](/vault/docs/secrets/key-management/gcpkms#authentication)
section for details on precedence.
- `service_account_file` `(string: <required>)` - The path to a Google service account key file. The
key file must be readable on the host that Vault server is running on. May also be provided by the
`GOOGLE_CREDENTIALS` environment variable or by
[application default credentials](https://cloud.google.com/docs/authentication/production).

555
website/content/api-docs/secret/key-management/index.mdx
View file

@ -1,555 +0,0 @@
---
layout: api
page_title: Key Management - Secrets Engines - HTTP API
description: The API documentation for the Key Management secrets engine.
---
> [!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.
# Key management secrets engine (API)
This is the API documentation for the Key Management secrets engine. For general
information about the usage and operation of the secrets engine, please see the
[Key Management secrets engine documentation](/vault/docs/secrets/key-management).
This documentation assumes the Key Management secrets engine is enabled at the
`/keymgmt` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
## Create key
This endpoint creates a named cryptographic key of a specified type. These parameters
set cannot be changed after key creation.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/key/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to create.
This is provided as part of the request URL.
- `type` `(string: "rsa-2048")` – Specifies the type of cryptographic key to create. The
following key types are supported:
- `aes256-gcm96` - AES-GCM with a 256-bit AES key and a 96-bit nonce (symmetric)
- `rsa-2048` - RSA with bit size of 2048 (asymmetric)
- `rsa-3072` - RSA with bit size of 3072 (asymmetric)
- `rsa-4096` - RSA with bit size of 4096 (asymmetric)
- `ecdsa-p256` - ECDSA using the P-256 elliptic curve (asymmetric)
- `ecdsa-p384` - ECDSA using the P-384 elliptic curve (asymmetric)
- `ecdsa-p521` - ECDSA using the P-521 elliptic curve (asymmetric)
### Sample payload
```json
{
"type": "rsa-2048"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/keymgmt/key/example-key
```
## Read key
This endpoint returns information about a named key. The `keys` object will hold information
regarding each key version. Different information will be returned depending on the key type.
For example, an asymmetric key will return its public key in a PEM encoding.
| Method | Path |
| :----- | :------------------- |
| `GET` | `/keymgmt/key/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to read.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/keymgmt/key/example-key
```
### Sample response
```json
{
"data": {
"deletion_allowed": false,
"keys": {
"1": {
"creation_time": "2020-11-02T15:54:58.768473-08:00",
"public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
},
"2": {
"creation_time": "2020-11-04T16:58:47.591718-08:00",
"public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
}
},
"latest_version": 2,
"min_enabled_version": 1,
"name": "example-key",
"type": "rsa-2048"
}
}
```
## List keys
This endpoint returns a list of all existing keys.
| Method | Path |
| :----- | :------------- |
| `LIST` | `/keymgmt/key` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/keymgmt/key
```
### Sample response
```json
{
"data": {
"keys": ["example-key"]
}
}
```
## Update key
This endpoint updates a named key.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/key/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to update.
This is provided as part of the request URL.
- `min_enabled_version` `(int: 0)` – Specifies the minimum enabled version of the key. All
versions of the key less than the specified version will be disabled for cryptographic
operations in the KMS provider that the key has been distributed to. Setting this value to
`0` means that all versions will be enabled.
- `deletion_allowed` `(bool: false)` – Specifies if the key is allowed to be deleted.
### Sample payload
```json
{
"min_enabled_version": 0,
"deletion_allowed": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/keymgmt/key/example-key
```
## Rotate key
This endpoint rotates the version of a named key.
| Method | Path |
| :----- | :-------------------------- |
| `POST` | `/keymgmt/key/:name/rotate` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to rotate.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/keymgmt/key/example-key/rotate
```
## Delete key
This endpoint deletes a named key. The key must be removed from all KMS providers that it's
been distributed to and have `deletion_allowed` set to `true` in order to be deleted.
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/keymgmt/key/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to delete.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/keymgmt/key/example-key
```
## List KMS providers of key
This endpoint returns a list of all KMS providers that the named key has been distributed to.
Currently, a key can only be distributed to a single KMS provider.
| Method | Path |
| :----- | :----------------------- |
| `LIST` | `/keymgmt/key/:name/kms` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/keymgmt/key/example-key/kms
```
### Sample response
```json
{
"data": {
"keys": ["example-kms"]
}
}
```
## Create/Update KMS provider
This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.
| Method | Path |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
This is provided as part of the request URL.
- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
Vault. Cannot be changed after creation. For more information about each provider, refer to
the [KMS Providers](/vault/docs/secrets/key-management#kms-providers) section. The following values
are supported:
- `azurekeyvault`
- `awskms`
- `gcpckms`
### Common parameters
There are common parameters that expect different values depending on the specified `provider`.
Please reference the API documentation for individual KMS providers to determine which values to
set for each of the parameters listed below.
- `key_collection` `(string: <required>)` – Refers to a location to store keys in the specified
`provider`. Cannot be changed after creation. The expected value for this parameter will differ
depending on the specified `provider`.
- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
the specified `provider`. Supplying values for this parameter is optional, as credentials may
also be specified as environment variables. The expected keys and values for this parameter
will differ depending on the specified `provider`.
### Sample payload
```json
{
"credentials": [
"client_id=example-client-id",
"client_secret=example-client-secret",
"tenant_id=example-tenant-id"
],
"key_collection": "example-keyvault-name",
"provider": "azurekeyvault"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```
## Read KMS provider
This endpoint returns information about a KMS provider.
| Method | Path |
| :----- | :------------------- |
| `GET` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to read.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```
### Sample response
```json
{
"data": {
"key_collection": "example-keyvault-name",
"provider": "azurekeyvault"
}
}
```
## List KMS providers
This endpoint returns a list of all existing KMS providers.
| Method | Path |
| :----- | :------------- |
| `LIST` | `/keymgmt/kms` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/keymgmt/kms
```
### Sample response
```json
{
"data": {
"keys": ["example-kms"]
}
}
```
## Delete KMS provider
This endpoint deletes a KMS provider. A KMS provider cannot be deleted until all keys
that have been distributed to it are removed.
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/keymgmt/kms/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to delete.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```
## Distribute key to KMS provider
This endpoint distributes a named key to the KMS provider. The key will be securely delivered
(i.e., wrapped for protection in transit) following the key import specification of the KMS
provider. The parameters set cannot be changed after the key has been distributed.
| Method | Path |
| :----- | :--------------------------------- |
| `POST` | `/keymgmt/kms/:name/key/:key_name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider to distribute the given key
to. This is provided as part of the request URL.
- `key_name` `(string: <required>)` – Specifies the name of the key to distribute to the given KMS
provider. This is provided as part of the request URL.
- `purpose` `([]string: <required>)` – Specifies the purpose of the key. The purpose defines a set
of cryptographic capabilities that the key will have in the KMS provider. A key must have at
least one of the supported purposes. The following values are supported:
- `encrypt`
- `decrypt`
- `sign`
- `verify`
- `wrap`
- `unwrap`
- `protection` `(string: "hsm")` – Specifies the protection of the key. The protection defines
where cryptographic operations are performed with the key in the KMS provider. The following
values are supported:
- `hsm`
- `software`
### Sample payload
```json
{
"protection": "hsm",
"purpose": "encrypt,decrypt"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```
## Read key in KMS provider
This endpoint returns information about a key that's been distributed to a KMS provider.
| Method | Path |
| :----- | :--------------------------------- |
| `GET` | `/keymgmt/kms/:name/key/:key_name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
part of the request URL.
- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```
### Sample response
```json
{
"data": {
"name": "example-key-<unix_timestamp>",
"protection": "hsm",
"purpose": "encrypt,decrypt",
"versions": {
"1": "c96a8956194f4632bc3837b64a1b45b1",
"2": "01ce657d33f64eb38f9432be543f3f52"
}
}
}
```
## List keys in KMS provider
This endpoint returns a list of all keys that have been distributed to the given KMS
provider. Many keys can be distributed to a single KMS provider.
| Method | Path |
| :----- | :----------------------- |
| `LIST` | `/keymgmt/kms/:name/key` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider.
This is provided as part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key
```
### Sample response
```json
{
"data": {
"keys": ["example-key"]
}
}
```
## Remove key from KMS provider
This endpoint removes a named key from the KMS provider. This will only delete the key from
the KMS provider. The key will still exist in the secrets engine and can be redistributed to
a KMS provider at a later time. To permanently delete the key from the secrets engine, the
[Delete Key](#delete-key) API must be invoked.
| Method | Path |
| :------- | :--------------------------------- |
| `DELETE` | `/keymgmt/kms/:name/key/:key_name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
part of the request URL.
- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```

612
website/content/api-docs/secret/kmip.mdx
View file

@ -1,612 +0,0 @@
---
layout: api
page_title: KMIP - Secrets Engines - HTTP API
description: This is the API documentation for the Vault KMIP secrets engine.
---
> [!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.
# KMIP secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault KMIP secrets engine. For general
information about the usage and operation of
the KMIP secrets engine, please see [these docs](/vault/docs/secrets/kmip).
This documentation assumes the KMIP secrets engine is enabled at the `/kmip` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.
## Write config
| Method | Path |
| :----- | :------------- |
| `POST` | `/kmip/config` |
This endpoint configures shared information for the secrets engine. After writing
to it the KMIP engine will generate a CA and start listening for KMIP requests.
If the server was already running and any non-client settings are changed, the
server will be restarted using the new settings. All generated CAs will use
entropy augmentation to generate their certificates if entropy augmentation
is enabled.
### Parameters
- `listen_addrs` (`list: ["127.0.0.1:5696"] || string`) - Address and port the
KMIP server should listen on. Can be given as a JSON list or a
comma-separated string list. If multiple values are given, all will be
listened on.
- `connection_timeout` (`int: 1 || string:"1s"`) - Duration in either an integer
number of seconds (10) or an integer time unit (10s) within which connections
must become ready.
- `server_hostnames` (`list: ["localhost"] || string`) - Hostnames to include in
the server's TLS certificate as SAN DNS names. The first will be used as the
common name (CN).
- `server_ips` (`list: [] || string`) - IPs to include in the server's TLS
certificate as SAN IP addresses. Localhost (IPv4 and IPv6) will be automatically
included.
- `tls_ca_key_type` (`string: "ec"`) - CA key type, `rsa` or `ec`.
- `tls_ca_key_bits` (`int: 521`) - CA key bits, valid values depend on key type.
- `tls_min_version` (`string: "tls12"`) - Minimum TLS version to accept.
- `default_tls_client_key_type` (`string: "ec"`): - Client certificate key type,
`rsa` or `ec`.
- `default_tls_client_key_bits` (`int: 521`): - Client certificate key bits, valid
values depend on key type.
- `default_tls_client_ttl` (`int: 86400 || string:"24h"`) – Client certificate
TTL in either an integer number of seconds (10) or an integer time unit (10s).
### Sample payload
```json
{
"listen_addrs": "127.0.0.1:5696,192.168.1.2:9000",
"connection_timeout": "1s",
"server_hostnames": "myhostname1,myhostname2",
"server_ips": "192.168.1.2",
"tls_ca_key_type": "ec",
"tls_ca_key_bits": 521,
"tls_min_version": "tls11",
"default_tls_client_key_type": "ec",
"default_tls_client_key_bits": 224,
"default_tls_client_ttl": 86400
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/kmip/config
```
## Read config
| Method | Path |
| :----- | :------------- |
| `GET` | `/kmip/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/kmip/config
```
### Sample response
```json
{
"data": {
"listen_addrs": ["127.0.0.1:5696", "192.168.1.2:9000"],
"connection_timeout": "1s",
"server_hostnames": ["myhostname1", "myhostname2"],
"server_ips": ["192.168.1.2"],
"tls_ca_key_type": "ec",
"tls_ca_key_bits": 521,
"tls_min_version": "tls11",
"default_tls_client_key_type": "ec",
"default_tls_client_key_bits": 224,
"default_tls_client_ttl": 86400
}
}
```
## Read CA
| Method | Path |
| :----- | :--------- |
| `GET` | `/kmip/ca` |
Returns the CA certificates in PEM format. Returns an error if config has never
been written.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/kmip/ca
```
### Sample response
```json
{
"data": {
"ca_pem": "-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUApNsRil/dzQy3XT+yjZQEpcA49kwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MzIzM1oX\nDTI5MDYyMTE4MzMwM1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAGWJGwPjGGoXivBv\nLJwR+fIG3z6Ei06bhZgTaRW/U3eA5oivxubxOVZPe1BJGWCsIVNjxMZAN4Pswki7\nAHme9bdJAUbQw33tC1iAb0wjzIpoPv1+pdSk6wYZTCKzOYWCbsTb3SOIetpk7sQw\niM17agwIRK9qGvX3Q4PBfEKEpstAjoaJo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUKMwPpRxU2Uzydv21bc8ePfUpGFEw\nHwYDVR0jBBgwFoAUwrPrJc9EsU6kTWJ5hXkJV4PEq9swCgYIKoZIzj0EAwIDgYwA\nMIGIAkIBRCarRMer42Ni/fKQBTi+uFk+2sPyCxCYDWTfMFAusC51dC2F91mUL77R\nkHxauSkh5gcZVAch/dg/L0ewP0AZUBUCQgE1VqoBN9klFky7LHfl62p6PgprH7d1\nYCvYVbWdBNnEdrL2P9aKsuCewdqycZVJLmM36cHnOAEGg1yea8soQL0Ylw==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOBgW1GCH+n5gC6m8Ff5jq+5DmO8wCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MzIzM1oX\nDTI5MDYyMTE4MzMwM1owHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQA7vkbmKJR+SVBTJjAFnma0ynTIi64doZA\n5oOXIAExvOyyI2KBNfqXxgzt/51u9vvixQf3VX/1Jph+0fkIcIYUEmIBFAH7Th1X\n0EOOdmMHfN0YkXDEUUdKIZyQxgA7o3DF+JAVg1cdBV7S8jZyXik7pL+IFnlYdfvN\nUZcArUkMfKo1cZajZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBTCs+slz0SxTqRNYnmFeQlXg8Sr2zAfBgNVHSMEGDAWgBTC\ns+slz0SxTqRNYnmFeQlXg8Sr2zAKBggqhkjOPQQDAgOBiwAwgYcCQgGjKAC371/5\npxgYdLVBmVC6Aa+oOvwGfnich2YLSLbThySED7+fXl1BY43VU703ad6M34fStf6z\nwFZvVZVK188DCQJBJcSZ7YA3PjOre+epJHtAba+1CkAdbSAeGhBDgHdIEP1/FDvx\n+U2QYeVZ7kAVnkzPxa17V0yqjxDtQDTiOw/ZV5c=\n-----END CERTIFICATE-----"
}
}
```
## Write scope
| Method | Path |
| :----- | :------------------- |
| `POST` | `/kmip/scope/:scope` |
Creates a new scope with the given name.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/kmip/scope/myscope
```
## List scopes
| Method | Path |
| :----- | :------------ |
| `LIST` | `/kmip/scope` |
List existing scopes.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/kmip/scope
```
### Sample response
```json
{
"data": {
"keys": ["myscope"]
}
}
```
## Delete scope
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/kmip/scope/:scope` |
Delete a scope by name.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `force` (`bool: false`) - Force scope deletion. If KMIP managed objects have
been created within the scope this param must be provided or the deletion will
fail. This value should be supplied as a query parameter, or as an argument in
the CLI.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/kmip/scope/myscope?force=false
```
## Write role
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/kmip/scope/:scope/role/:role` |
Creates or updates a role.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
- `tls_client_key_type` (`string`): - Client certificate key type,
`rsa` or `ec`. Overrides engine-wide default managed in `config` endpoint.
- `tls_client_key_bits` (`int`): - Client certificate key bits, valid
values depend on key type. Overrides engine-wide default managed in `config`
endpoint.
- `tls_client_ttl` (`int or string`) – Client certificate
TTL in either an integer number of seconds (10) or an integer time unit (10s).
Overrides engine-wide default managed in `config` endpoint.
- `operation_none` (`bool: false`) - Remove all permissions
from this role. May not be specified with any other
`operation_` params.
- `operation_all` (`bool: false`) - Grant all permissions
to this role. May not be specified with any other
`operation_` params.
- `operation_activate` (`bool: false`) - Grant permission to use the KMIP
`Activate` operation.
- `operation_add_attribute` (`bool: false`) - Grant permission to use the KMIP
`Add Attribute` operation.
- `operation_create` (`bool: false`) - Grant permission to use the KMIP
`Create` operation.
- `operation_decrypt` (`bool: false`) - Grant permission to use the KMIP
`Decrypt` operation.
- `operation_destroy` (`bool: false`) - Grant permission to use the KMIP
`Destroy` operation.
- `operation_discover_versions` (`bool: false`) - Grant permission to use the KMIP
`Discover Versions` operation.
- `operation_encrypt` (`bool: false`) - Grant permission to use the KMIP
`Encrypt` operation.
- `operation_get` (`bool: false`) - Grant permission to use the KMIP
`Get` operation.
- `operation_get_attribute_list` (`bool: false`) - Grant permission to use the KMIP
`Get Attribute List` operation.
- `operation_get_attributes` (`bool: false`) - Grant permission to use the KMIP
`Get Attributes` operation.
- `operation_import` (`bool: false`) - Grant permission to use the KMIP
`Import` operation.
- `operation_locate` (`bool: false`) - Grant permission to use the KMIP
`Locate` operation.
- `operation_query` (`bool: false`) - Grant permission to use the KMIP
`Query` operation.
- `operation_register` (`bool: false`) - Grant permission to use the KMIP
`Register` operation.
- `operation_rekey` (`bool: false`) - Grant permission to use the KMIP
`Rekey` operation.
- `operation_revoke` (`bool: false`) - Grant permission to use the KMIP
`Revoke` operation.
### Sample payload
```json
{
"operation_activate": true,
"operation_add_attribute": true,
"operation_create": true,
"operation_decrypt": true,
"operation_destroy": true,
"operation_discover_versions": true,
"operation_encrypt": true,
"operation_get": true,
"operation_get_attribute_list": true,
"operation_get_attributes": true,
"operation_import": true,
"operation_locate": true,
"operation_query": true,
"operation_register": true,
"operation_rekey": true,
"operation_revoke": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole
```
## Read role
| Method | Path |
| :----- | :------------------------------ |
| `GET` | `/kmip/scope/:scope/role/:role` |
Read a role.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole
```
### Sample response
```json
{
"data": {
"operation_activate": true,
"operation_add_attribute": true,
"operation_create": true,
"operation_decrypt": true,
"operation_destroy": true,
"operation_discover_versions": true,
"operation_encrypt": true,
"operation_get": true,
"operation_get_attribute_list": true,
"operation_get_attributes": true,
"operation_import": true,
"operation_locate": true,
"operation_query": true,
"operation_register": true,
"operation_rekey": true,
"operation_revoke": true
}
}
```
## List roles
| Method | Path |
| :----- | :------------------------ |
| `LIST` | `/kmip/scope/:scope/role` |
List roles with a scope.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role
```
### Sample response
```json
{
"data": {
"keys": ["myrole"]
}
}
```
## Delete role
| Method | Path |
| :------- | :------------------------------ |
| `DELETE` | `/kmip/scope/:scope/role/:role` |
Delete a role by name.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole
```
## Generate credential
| Method | Path |
| :----- | :-------------------------------------------------- |
| `POST` | `/kmip/scope/:scope/role/:role/credential/generate` |
Create a new client certificate tied to the given role and scope.
This endpoint uses entropy augmentation to generate the client certificate
if entropy augmentation is enabled.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
- `format` (`string: "pem"`) - Format to return the certificate, private key,
and CA chain in. One of `pem`, `pem_bundle`, or `der`.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/generate
```
### Sample response
```json
{
"data": {
"ca_chain": [
"-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUKOGtsdXdMjjGni52EsaMQ7ozhCEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEATHNhNvU0GMtzl6A\nPbNaCoF0jV3z09RCfLKEqMl/MXv/AlPcfiqCQeOWBwWHv76epPWkCCo+IlNq8ldQ\neVe52p6mABMvRjE6BZ/eLea27zImI6waK7nZ2hqx0npb8ivdbwmrgp0NQnv0sJ+o\nPeLa2vh9wDK1NJebmOv0yRAbCw2CH7Rbo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQU2naFRym+xfFvZm2TNRBXNf3MJSsw\nHwYDVR0jBBgwFoAUFrA/R807R0BnIt395KzaXdP4n00wCgYIKoZIzj0EAwIDgYwA\nMIGIAkIAkb8EdHCXgPpQsKYedMz4X2j5CFSVdZTWsPVw1XuSXIsIsc6018V4z9Kp\nkPacsHZTBR636y2toqRPDG4y9MLqFFkCQgCV1jEkiNhhKc+ZWuDjerdqNvLnCbe+\n7t4fiG9zQgWwh6IxL11cNyGVz9gS9af32DtuYf0xwFLOwLgn1RadC9Pd7Q==\n-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOcs4pXlp+UgGiUKfKlcxIE/woPEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAcst7uNwu77WtLDkbz4ILYDiQ3BgS++qU\nOoNKcKyvNe8YX6PtrdQWPTaxT4MZNHZvTv+BAQTQqGLKrstpkjXPh+sBn7V4trkT\nMCtxUjIGneURUXS4IC/KJEA60P7ep7MrGnJfG/N4m+Q/a6BuxKhdEavXtepniCMz\npHw4DCpW/9m2t16jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQWsD9HzTtHQGci3f3krNpd0/ifTTAfBgNVHSMEGDAWgBQW\nsD9HzTtHQGci3f3krNpd0/ifTTAKBggqhkjOPQQDAgOBiwAwgYcCQR7iNoA4nBV3\ndSn8nfafklFvHZxoKR1j3nn+56z4JHD6TNr//GNqQiqnM3P//Tce+E4KzEax4xRg\nhaLURgPLNBjOAkIAqW+1/+v9D0vXOU1WPc+/oFvhSjYnr5qqcTL7by5fsmMXzAIe\nLODXiODxdppXXnMZPCPZh6MGgUwEGYeCnaXopWc=\n-----END CERTIFICATE-----"
],
"certificate": "-----BEGIN CERTIFICATE-----\nMIICOzCCAZygAwIBAgIUeOkn0HAdoh31nGkVKdafpCNuhFEwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTAwMDlaFw0xOTA2MjUxOTAwMzlaMCAxDjAMBgNVBAsTBWlsVjYzMQ4w\nDAYDVQQDEwUyRnlWTjCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAA0rIy0h2DL3\nzmTXVj2v22Kz0N1EUUATlRgBj1XBsBA1Pdd7CSZoefmh/u6Z8TjtRX9Z1aj9Bb/d\nJxS3zB4mguULAF4k7bLH1gKXMVC6NYjjk3mfxH5jG4QY8S8n6uyqzNgI5KRJ2Hyj\nm8549Nvq3rvs8yOVXPSOGzkJ5KdUmSvXicMQo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFEuzruLILCil5Fp32ZjE4AhD\nU268MB8GA1UdIwQYMBaAFNp2hUcpvsXxb2ZtkzUQVzX9zCUrMAoGCCqGSM49BAMC\nA4GMADCBiAJCAeeuaIsgO9ro7opzZ9y9hSHkKB5WA5Qc7ePoSiKHNNbVvIJMkjRQ\nC9YtUMQNnQ8wE6D/9xvR+9OBIi7t16iHGPGbAkIA6WIG6HHRNUXnHPIiW8iy/04O\nfVqZgJHJEeyGQbwdaehs+Z5xOz6TA4Z3uZOAMnPcb+KDwchnQ8CJnmT/KnnT5D8=\n-----END CERTIFICATE-----",
"private_key": "-----BEGIN EC PRIVATE KEY-----\nMIHcAgEBBEIBB4xDj9SUtb6Z466lVQIf3ucy21q5S2Fp9bzTQ0Ch5Vg2+DhUZUa1\nDjKvDdICY6hLPBFAwcOUFdDXr4kH/i8wuRWgBwYFK4EEACOhgYkDgYYABAANKyMt\nIdgy985k11Y9r9tis9DdRFFAE5UYAY9VwbAQNT3XewkmaHn5of7umfE47UV/WdWo\n/QW/3ScUt8weJoLlCwBeJO2yx9YClzFQujWI45N5n8R+YxuEGPEvJ+rsqszYCOSk\nSdh8o5vOePTb6t677PMjlVz0jhs5CeSnVJkr14nDEA==\n-----END EC PRIVATE KEY-----",
"serial_number": "728181095563584845125173905844944137943705466376"
}
}
```
## Sign CSR
| Method | Path |
| :----- | :---------------------------------------------- |
| `POST` | `/kmip/scope/:scope/role/:role/credential/sign` |
Create a new client certificate tied to the given role and scope,
based on a Certificate Signing Request (CSR) provided as input.
The key type and key bits used in the CSR must match those of the role.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
- `format` (`string: "pem"`) - Format to return the certificate, private key,
and CA chain in. One of `pem`, `pem_bundle`, or `der`.
- `csr` (`string`) - CSR in PEM format.
### Sample request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC5DCCAcwCAQIwaTEMMAoGA1UEAwwDRUtNMQ8wDQYDVQQKDAZOZXRBcHAxEjAQ\nBgNVBAsMCVNvbGlkRmlyZTESMBAGA1UEBwwJU3Vubnl2YWxlMRMwEQYDVQQIDApD\nYWxpZm9ybmlhMQswCQYDVQQGEwJVUzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBALFjeR5ZeKlTSLNKLr0Gl4DEH1oICDZj3oMYAEGMO/uW/4YleFmYSkPc\nxqqT/i6nlys+ZvLMtFdTr4lZBVsVD/AhjDVVBKuxaHIbolZFBjVxY3J2MuCWS2hB\nN2pRmGgnlpPwiu0VpA1bNJ/Shw3Zol9OnYliZAzc6U/hMxDUP7yQHSU5Q9T3vHV2\n3xR38PmeXKqdG+S68/cuhEHtUPa1mTagntkYU5BDOKpcmPenEam7itR+Tp1yZupp\n5sdfI/5trO4YI6jtUmMsA5PaNlKMDqzwjkiI8+kd+aDgIJa5c9VeEXC/PkjXRJ9G\nC/mSQOhM84EaYAU6zDw9B78j5ca2izsCAwEAAaA2MDQGCSqGSIb3DQEJDjEnMCUw\nDgYDVR0PAQH/BAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMCMA0GCSqGSIb3DQEB\nCwUAA4IBAQBXW2nA4EsNYDLo8gzBqsM3AFYTdYTO+Q2wu0fUZp3cX3AOIYFstW6/\nrCpdU3/z5ICS9i4ZHfJOAeKtBeOE+VCt7xI/+ZH1D7I9mNWZ7wp+ZXWImzRtEmBZ\nSj6wVa2Igmtiqr2UQegWnp5MG5Ds37DvmBoFDvcGMKy3tVJamSXFhqtdY2QSzYMM\nCjuqNUjll4RUUurjKmET8ZVHjLXGI3MxGVVg6aC3TtYuK12DFEFSy8LlfVn6kXS4\nPTe4Y6ffW5JykdW85xMq5RM6rpwsrVaKvVFOwn9O7lGZLeq4HFPcjY2SXZxAT+bi\nb/t+UQOjhlb0X2YdjPGHjFd+spZQ6u0a\n-----END CERTIFICATE REQUEST-----"}'
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/sign
```
### Sample response
```json
{
"data": {
"ca_chain": [
"-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUKOGtsdXdMjjGni52EsaMQ7ozhCEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEATHNhNvU0GMtzl6A\nPbNaCoF0jV3z09RCfLKEqMl/MXv/AlPcfiqCQeOWBwWHv76epPWkCCo+IlNq8ldQ\neVe52p6mABMvRjE6BZ/eLea27zImI6waK7nZ2hqx0npb8ivdbwmrgp0NQnv0sJ+o\nPeLa2vh9wDK1NJebmOv0yRAbCw2CH7Rbo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQU2naFRym+xfFvZm2TNRBXNf3MJSsw\nHwYDVR0jBBgwFoAUFrA/R807R0BnIt395KzaXdP4n00wCgYIKoZIzj0EAwIDgYwA\nMIGIAkIAkb8EdHCXgPpQsKYedMz4X2j5CFSVdZTWsPVw1XuSXIsIsc6018V4z9Kp\nkPacsHZTBR636y2toqRPDG4y9MLqFFkCQgCV1jEkiNhhKc+ZWuDjerdqNvLnCbe+\n7t4fiG9zQgWwh6IxL11cNyGVz9gS9af32DtuYf0xwFLOwLgn1RadC9Pd7Q==\n-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOcs4pXlp+UgGiUKfKlcxIE/woPEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAcst7uNwu77WtLDkbz4ILYDiQ3BgS++qU\nOoNKcKyvNe8YX6PtrdQWPTaxT4MZNHZvTv+BAQTQqGLKrstpkjXPh+sBn7V4trkT\nMCtxUjIGneURUXS4IC/KJEA60P7ep7MrGnJfG/N4m+Q/a6BuxKhdEavXtepniCMz\npHw4DCpW/9m2t16jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQWsD9HzTtHQGci3f3krNpd0/ifTTAfBgNVHSMEGDAWgBQW\nsD9HzTtHQGci3f3krNpd0/ifTTAKBggqhkjOPQQDAgOBiwAwgYcCQR7iNoA4nBV3\ndSn8nfafklFvHZxoKR1j3nn+56z4JHD6TNr//GNqQiqnM3P//Tce+E4KzEax4xRg\nhaLURgPLNBjOAkIAqW+1/+v9D0vXOU1WPc+/oFvhSjYnr5qqcTL7by5fsmMXzAIe\nLODXiODxdppXXnMZPCPZh6MGgUwEGYeCnaXopWc=\n-----END CERTIFICATE-----"
],
"certificate": "-----BEGIN CERTIFICATE-----\nMIICOzCCAZygAwIBAgIUeOkn0HAdoh31nGkVKdafpCNuhFEwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTAwMDlaFw0xOTA2MjUxOTAwMzlaMCAxDjAMBgNVBAsTBWlsVjYzMQ4w\nDAYDVQQDEwUyRnlWTjCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAA0rIy0h2DL3\nzmTXVj2v22Kz0N1EUUATlRgBj1XBsBA1Pdd7CSZoefmh/u6Z8TjtRX9Z1aj9Bb/d\nJxS3zB4mguULAF4k7bLH1gKXMVC6NYjjk3mfxH5jG4QY8S8n6uyqzNgI5KRJ2Hyj\nm8549Nvq3rvs8yOVXPSOGzkJ5KdUmSvXicMQo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFEuzruLILCil5Fp32ZjE4AhD\nU268MB8GA1UdIwQYMBaAFNp2hUcpvsXxb2ZtkzUQVzX9zCUrMAoGCCqGSM49BAMC\nA4GMADCBiAJCAeeuaIsgO9ro7opzZ9y9hSHkKB5WA5Qc7ePoSiKHNNbVvIJMkjRQ\nC9YtUMQNnQ8wE6D/9xvR+9OBIi7t16iHGPGbAkIA6WIG6HHRNUXnHPIiW8iy/04O\nfVqZgJHJEeyGQbwdaehs+Z5xOz6TA4Z3uZOAMnPcb+KDwchnQ8CJnmT/KnnT5D8=\n-----END CERTIFICATE-----",
"serial_number": "728181095563584845125173905844944137943705466376"
}
}
```
## Lookup credential
| Method | Path |
| :----- | :------------------------------------------------ |
| `GET` | `/kmip/scope/:scope/role/:role/credential/lookup` |
Read a certificate by serial number. The private key cannot be obtained except
at generation time.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
- `serial_number` (`string: <required>`) - Serial number of certificate to revoke.
- `format` (`string: "pem"`) - Format to return the certificate, private key,
and CA chain in. One of `pem`, `pem_bundle`, or `der`.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/lookup?serial_number=728181095563584845125173905844944137943705466376
```
### Sample response
```json
{
"data": {
"ca_chain": [
"-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUGptwpwpVvxlx3sBniJ7TRGD9gCkwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE5MDY0N1oX\nDTI5MDYyMTE5MDcxN1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEADO48mMu5V2PTbcg\nq0JPB5ReWwnUHhfFh/+XLP8ZM112JpOFutlcUYYZ23jAlvrlYZ+m1E0ASr0592ZM\n9CwIXy3zAJChPrV3tiofhINR5PPqCF42FcfNj4l7VN/XeYMN6dslX+O4dPn/DsbH\nZi7kWr5KSOR939ULFaRMYe3l2MxaYZ2do2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUPP7VJOGk3qR0qKqx3TLN1R8JDiQw\nHwYDVR0jBBgwFoAUBHr+hhaorPU2jIF35DTBDhL7uWowCgYIKoZIzj0EAwIDgYwA\nMIGIAkIA7G82rqLYb6bKrQZzhpNwvVIFOSocEJrUbP0E0D8dEeOmKs43C70P5e0s\nTrrpNAMEsK6vXWtM+QcrZZp+yyM6k3QCQgG8cxFIl8tgoMKWe0+cDeOoHtczopRy\nSk+Tt7DNNP9sfYK11g7w8xzbtW4ZuZKKoYRbxN+eQHn5c+8akMSt4h71Dg==\n-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----\nMIICKDCCAYugAwIBAgIUWv6jrjNbsvdX43l4s10HaJkSxOMwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE5MDY0N1oX\nDTI5MDYyMTE5MDcxN1owHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAP6C8d9ZUalKBM1NdALtEMlv+dwFnK88F\n8bp7i6hV55vER45FtKKciQwWoA91FjfWTrDYPHb1X4OPZvcjQGnIJ1AAj+BSzEWr\neJXNo46RxLLl+cndiVDqlbJlhE9qVn9ueLHhPIPNSFZneY9cTj5+EOPyKiBCo4xB\ndTtVr29lLu/JwM2jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQEev6GFqis9TaMgXfkNMEOEvu5ajAfBgNVHSMEGDAWgBQE\nev6GFqis9TaMgXfkNMEOEvu5ajAKBggqhkjOPQQDAgOBigAwgYYCQUlJqNoWCz4H\npjMNphxD4A8lfWtIrajGUhSxE9+JWRzoPpEJSwVobvryU2SO5u0sfqxtcmX/sBjY\n12N5QVFfqpB3AkErsjg8eMkh+OMalmWxRYtTuZt+i4DPm1CKEVIkUT8ZBXYTIl9V\nG3TG8lmby/8e+YUwJEKVvOy6tVI8ExEoVslwKw==\n-----END CERTIFICATE-----"
],
"certificate": "-----BEGIN CERTIFICATE-----\nMIICOjCCAZygAwIBAgIUf4zFBobFJMkSIvM7CfceSVfYNggwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTA3MTBaFw0xOTA2MjUxOTA3NDBaMCAxDjAMBgNVBAsTBW5BcUswMQ4w\nDAYDVQQDEwU0Qjd2STCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAdxHrbr/EXUz\nzWCd9HMUDus6r/3QF1Y3u9dPD2UwM76J3aICmykkm7xoYpoyg4chBEDxBWh2YkGT\na4WFMoXBa+k1AZhdvlj8tjOUlYZrTCLB9FBPCGz3JB4f5cmbG5JVsQ8qnBPiyV3e\nU21cWM6mWlhZKHWIdBU2pj+eXW78K5LMu2sWo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFAT0QZOpZCTMCz7F8+BvF2xs\nZSfkMB8GA1UdIwQYMBaAFDz+1SThpN6kdKiqsd0yzdUfCQ4kMAoGCCqGSM49BAMC\nA4GLADCBhwJBPxBV4DgPi5zihRnxu7zTNeqe/xlvrEt1uTff8QtW3JsigbBDHV+A\nxBe7vc8mL8VQPG7BFKvvxuQvOAeeQ+AR8ZoCQgDtbaWgLtfbzKvwlY48e6dLeBpK\nDu1DaZq+79EON2lhWQ+ULHblJc5cK0F6Ff5OC89aDnV1TWQDHeR91mZdYiWZZQ==\n-----END CERTIFICATE-----",
"serial_number": "728181095563584845125173905844944137943705466376"
}
}
```
## List credential serial numbers
| Method | Path |
| :----- | :----------------------------------------- |
| `LIST` | `/kmip/scope/:scope/role/:role/credential` |
List the serial numbers of all certificates within a role.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential
```
### Sample response
```json
{
"data": {
"keys": ["728181095563584845125173905844944137943705466376"]
}
}
```
## Revoke credential
| Method | Path |
| :----- | :------------------------------------------------ |
| `POST` | `/kmip/scope/:scope/role/:role/credential/revoke` |
Delete a certificate, thereby revoking it.
### Parameters
- `scope` (`string: <required>`) - Name of scope. This is part of the request URL.
- `role` (`string: <required>`) - Name of role. This is part of the request URL.
- `serial_number` (`string: ""`) - Serial number of certificate to revoke.
Exactly one of `serial_number` or `certificate` must be provided.
- `certificate` (`string: """`) - Certificate to revoke, in PEM format.
Exactly one of `serial_number` or `certificate` must be provided.
### Sample payload
```json
{
"serial_number": "728181095563584845125173905844944137943705466376"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/revoke
```

440
website/content/api-docs/secret/kubernetes.mdx
View file

@ -1,440 +0,0 @@
---
layout: api
page_title: Kubernetes - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Kubernetes secrets engine.
---
> [!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.
# Kubernetes secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault Kubernetes secrets engine. To
learn more about the usage and operation, see the
[Kubernetes secrets engine documentation](/vault/docs/secrets/kubernetes).
This documentation assumes the Kubernetes secrets engine is mounted at the
`/kubernetes` path in Vault. Since it is possible to enable secrets engines at
any location, please update your API calls accordingly.
## Write configuration
This endpoint configures the plugin with the necessary information to reach the
Kubernetes API and authenticate with it.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/kubernetes/config` |
### Parameters
- `kubernetes_host` `(string: "https://$KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT_HTTPS")` -
Kubernetes API URL to connect to. Must be specified if the standard pod environment
variables `KUBERNETES_SERVICE_HOST` or `KUBERNETES_SERVICE_PORT_HTTPS` are not set.
- `kubernetes_ca_cert` `(string: "")` - PEM encoded CA certificate to verify the
Kubernetes API server certificate. Defaults to the local pod's CA certificate
at `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` if found, or
otherwise the host's root CA set.
- `service_account_jwt` `(string: "")` - The JSON web token of the service account
used by the secrets engine to manage Kubernetes credentials. Defaults to the local pod's
JWT at `/var/run/secrets/kubernetes.io/serviceaccount/token` if found.
- `disable_local_ca_jwt` `(bool: false)` - Disable defaulting to the local CA
certificate and service account JWT when running in a Kubernetes pod.
### Sample payload
```json
{
"kubernetes_host": "https://192.168.99.100:8443",
"kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/kubernetes/config
```
## Read configuration
Returns the config previously set, excluding credentials.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/kubernetes/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/kubernetes/config
```
### Sample response
```json
{
"data":{
"kubernetes_host": "https://192.168.99.100:8443",
"kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----",
"disable_local_ca_jwt": false
}
}
```
## Delete configuration
Deletes the config previously set.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/kubernetes/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE
http://127.0.0.1:8200/v1/kubernetes/config
```
## Create role
A role configures what service account tokens can be generated, and what
permissions will be attached to them. The permissions attached to a service
account token depend on the Kubernetes roles applied to its service account.
Each Kubernetes secrets engine role can operate in one of 3 modes. Each successive
mode generates more Kubernetes objects, and therefore requires more permissions
for Vault's own Kubernetes service account.
* Generate a service account token for a pre-existing service account - set `service_account_name`.
* Generate a service account _and_ a token, and bind a pre-existing Kubernetes role - set `kubernetes_role_name`.
* Generate a Kubernetes role, role binding, service account and token - set `generated_role_rules`.
Only one of `service_account_name`, `kubernetes_role_name` or
`generated_role_rules` can be set.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/kubernetes/roles/:name` |
### Parameters
- `name` `(string: <required>)` - The name of the role. Included in the path.
- `allowed_kubernetes_namespaces` `(array: [])` - The list of Kubernetes
namespaces this role can generate credentials for. If set to `"*"` all
namespaces are allowed. If set with `allowed_kubernetes_namespace_selector`, the conditions are
`OR`ed.
- `allowed_kubernetes_namespace_selector` `(string: "")` - A label selector for Kubernetes
namespaces in which credentials can be generated. Accepts either a JSON or YAML object. The value
should be of type
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta)
as illustrated in [Sample Payload 4](/vault/api-docs/secret/kubernetes#sample-payload-4) and
[Sample Payload 5](/vault/api-docs/secret/kubernetes#sample-payload-5) below.
If set with `allowed_kubernetes_namespaces`, the conditions are `OR`ed.
- `token_max_ttl` `(string: "")` - The maximum TTL for generated Kubernetes
tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`.
If not set or set to 0, the [system default](/vault/docs/configuration#max_lease_ttl) will be used.
- `token_default_ttl` `(string: "")` - The default TTL for generated Kubernetes
tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`.
If not set or set to 0, the [system default](/vault/docs/configuration#default_lease_ttl) will be used.
- `token_default_audiences` `(string: "")` - The default intended audiences for generated Kubernetes
tokens, specified by a comma separated string. e.g `"custom-audience-0,custom-audience-1"`.
If not set or set to `""`, the Kubernetes cluster default for audiences of service account tokens will be used.
- `service_account_name` `(string: "")` - The pre-existing service account to
generate tokens for. Mutually exclusive with all role parameters. If set, only
a Kubernetes token will be created when credentials are requested. See the
[Kubernetes service account documentation](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)
for more details on service accounts.
- `kubernetes_role_name` `(string: "")` - The pre-existing Role or ClusterRole
to bind a generated service account to. If set, Kubernetes token, service
account, and role binding objects will be created when credentials are requested.
See the [Kubernetes roles documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)
for more details on Kubernetes roles.
- `kubernetes_role_type` `(string: "Role")` - Specifies whether the Kubernetes
role is a `Role` or `ClusterRole`.
- `kubernetes_role_ref_type` `(string: "")` - Optional value indicating whether
the Kubernetes role referenced in the final RoleBinding is a Role or
ClusterRole. When left blank, Vault uses the value from `kubernetes_role_type`.
- `generated_role_rules` `(string: "")` - The Role or ClusterRole rules to use
when generating a role. Accepts either JSON or YAML formatted rules. If set, the
entire chain of Kubernetes objects will be generated when credentials are
requested. The value should be a `rules` key with an array of
[PolicyRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#policyrule-v1-rbac-authorization-k8s-io)
objects, as illustrated in the
[Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
and [Sample Payload 3](/vault/api-docs/secret/kubernetes#sample-payload-3) below.
- `name_template` `(string: "")` - The name template to use when generating
service accounts, roles and role bindings. If unset, a default template is
used. See [username templating](/vault/docs/concepts/username-templating)
for details on how to write a custom template.
- `extra_annotations` `(map<string|string>: nil)` - Additional annotations to
apply to all generated Kubernetes objects. See the
[Kubernetes annotations documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
for more details on annotations.
- `extra_labels` `(map<string|string>: nil)` - Additional labels to apply to
all generated Kubernetes objects. See the
[Kubernetes labels documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
for more details on labels.
### Sample payload 1
To generate tokens for a pre-existing service account:
```json
{
"allowed_kubernetes_namespaces": "*",
"service_account_name": "default",
"token_max_ttl": "24h"
}
```
### Sample payload 2
To generate tokens for a pre-existing ClusterRole:
```json
{
"allowed_kubernetes_namespaces": "*",
"kubernetes_role_type": "ClusterRole",
"kubernetes_role_name": "vault-k8s-secrets-role"
}
```
Or to define a secrets role of type `Role` but use a `ClusterRole` as reference
```json
{
"allowed_kubernetes_namespaces": "default",
"kubernetes_role_type": "Role",
"kubernetes_role_ref_type": "ClusterRole",
"kubernetes_role_name": "vault-k8s-secrets-role"
}
```
### Sample payload 3
To generate tokens for a defined set of Kubernetes role rules:
```json
{
"allowed_kubernetes_namespaces": "*",
"generated_role_rules": "rules:\n- apiGroups: [\"\"]\n resources: [\"pods\"]\n verbs: [\"list\"]\n",
}
```
Or to define the same rules as JSON:
```json
{
"allowed_kubernetes_namespaces": "*",
"generated_role_rules": "'rules': [{'apiGroups': [''],'resources': ['pods'],'verbs': ['list']}]"
}
```
### Sample payload 4
To generate tokens in namespaces based on a label selector for the namespaces:
```json
{
"allowed_kubernetes_namespace_selector": "matchLabels:\n stage: prod\n sa-generator: vault",
"service_account_name": "default",
}
```
Or to define the same selector as JSON:
```json
{
"allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}",
"service_account_name": "default",
}
```
### Sample payload 5
To generate tokens in namespaces based on a label selector for the namespaces and via a normal
namespace array:
```json
{
"allowed_kubernetes_namespaces": "vault-system,testing",
"allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}",
"service_account_name": "default",
}
```
In the payload above, the token can be generated for any namespace that either contains the labels
defined in the selector, or is named `vault-system` or `testing`.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/kubernetes/roles/default-role
```
## Read role
Returns the previously configured role.
| Method | Path |
| :----- | :---------------------------- |
| `GET` | `/kubernetes/roles/:name` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/kubernetes/role/default-role
```
### Sample response
```json
{
"data": {
"additional_metadata": {},
"allowed_kubernetes_namespaces": [
"*"
],
"generated_role_rules": "",
"kubernetes_role_name": "",
"kubernetes_role_type": "Role",
"kubernetes_role_ref_type": "Role",
"name": "default-role",
"name_template": "",
"service_account_name": "default",
"token_default_ttl": 0,
"token_max_ttl": 86400
}
}
```
## List roles
Lists all the roles that are configured.
| Method | Path |
| :----- | :-------------------------------- |
| `LIST` | `/kubernetes/roles` |
| `GET` | `/kubernetes/roles?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/kubernetes/roles
```
### Sample response
```json
{
"data": {
"keys": ["default-role", "prod-role"]
}
}
```
## Delete role
Deletes the previously configured role.
| Method | Path |
| :------- | :---------------------------- |
| `DELETE` | `/kubernetes/roles/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/kubernetes/role/default-role
```
## Generate credentials
Generate a service account token.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/kubernetes/creds/:role` |
### Parameters
- `role` `(string: <required>)` - Name of the role to generate credentials for.
- `kubernetes_namespace` `(string)` - The name of the Kubernetes
namespace in which to generate the credentials. Optional if the Vault role is configured
with a single namespace that is not `"*"`; required otherwise.
- `cluster_role_binding` `(bool: false)` - If true, generate a ClusterRoleBinding
to grant permissions across the whole cluster instead of within a namespace.
Requires the Vault role to have `kubernetes_role_type` set to ClusterRole.
- `ttl` `(string: "")` - The TTL of the generated Kubernetes service account token,
specified in seconds or as a Go duration format string, e.g. `"1h"`. The TTL
returned may be different from the TTL specified due to limits specified in
Kubernetes, Vault system-wide controls, or role-specific controls.
- `audiences` `(string: "")` - A comma separated string containing the intended audiences
of the generated Kubernetes service account the token, e.g. `"custom-audience-0,custom-audience-1"`.
If not set or set to `""`,
the [token_default_audiences](/vault/api-docs/secret/kubernetes#token_default_audiences) will be used.
### Sample payload
```json
{
"kubernetes_namespace": "default",
"ttl": "1h"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/kubernetes/creds/default-role
```
### Sample response
```json
{
"request_id": "58fefc6c-5195-c17a-94f2-8f889f3df57c",
"lease_id": "kubernetes/creds/default-role/aWczfcfJ7NKUdiirJrPXIs38",
"renewable": false,
"lease_duration": 3600,
"data": {
"service_account_name": "default",
"service_account_namespace": "default",
"service_account_token": "eyJhbG..."
}
}
```

18
website/content/api-docs/secret/kv/index.mdx
View file

@ -1,18 +0,0 @@
---
layout: api
page_title: KV - Secrets Engines - HTTP API
description: This is the API documentation for the Vault KV secrets engine.
---
> [!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.
# KV secrets engine (API)
This backend can be run in one of two versions. Each of which have a distinct API.
Choose the version below you are running. For more information on the KV secrets
engine see the [Vault kv documentation](/vault/docs/secrets/kv).
- [KV Version 1 API](/vault/api-docs/secret/kv/kv-v1)
- [KV Version 2 API](/vault/api-docs/secret/kv/kv-v2)

211
website/content/api-docs/secret/kv/kv-v1.mdx
View file

@ -1,211 +0,0 @@
---
layout: api
page_title: KV - Secrets Engines - HTTP API
description: This is the API documentation for the Vault KV secrets engine, version 1.
---
> [!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.
# KV secrets engine - version 1 (API)
This is the API documentation for the Vault KV secrets engine. For general
information about the usage and operation of the version 1 KV secrets engine, please
see the [Vault KV documentation](/vault/docs/secrets/kv/kv-v1). For information
about the differences between KV version 1 and version 2, please [see the KV overview
documentation](/vault/docs/secrets/kv).
~> Note: This documentation assumes the kv secrets engine is enabled at the
`/secret` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
## Read secret
This endpoint retrieves the secret at the specified location.
| Method | Path |
| :----- | :-------------- |
| `GET` | `/secret/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL.
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
### Sample requests
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/my-secret
```
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
```
### Sample response
```json
{
"auth": null,
"data": {
"foo": "bar",
"ttl": "1h"
},
"lease_duration": 3600,
"lease_id": "",
"renewable": false
}
```
_Note_: the `lease_duration` field, which will be populated if a "ttl" field
was included in the data, is advisory. No lease is created. This is a way for
writers to indicate how often a given value should be re-read by the client.
See the [Vault KV secrets engine documentation](/vault/docs/secrets/kv/kv-v1#ttls)
for more details.
## List secrets
This endpoint returns a list of key names at the specified location. Folders are
suffixed with `/`. The input must be a folder; list on a file will not return a
value. Note that no policy-based filtering is performed on keys; do not encode
sensitive information in key names. The values themselves are not accessible via
this API.
| Method | Path |
| :----- | :-------------- |
| `LIST` | `/secret/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
This is specified as part of the URL.
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
### Sample requests
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/secret/my-secret
```
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
```
### Sample response
The example below shows output for a query path of `secret/` when there are
secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two
entries.
```json
{
"auth": null,
"data": {
"keys": ["foo", "foo/"]
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Create/Update secret
This endpoint stores a secret at the specified location. If the value does not
yet exist, the calling token must have an ACL policy granting the `create`
capability. If the value already exists, the calling token must have an ACL
policy granting the `update` capability.
| Method | Path |
| :----- | :-------------- |
| `POST` | `/secret/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secrets to
create/update. This is specified as part of the URL.
- `:key` `(string: "")` – Specifies a key in the payload, paired with an associated value, to
be held at the given location. Multiple key/value pairs can be specified, and
all will be returned on a read operation. A key called `ttl` will trigger
some special behavior. See the [Vault KV secrets engine
documentation](/vault/docs/secrets/kv/kv-v1#ttls) for details.
### Sample payload
```json
{
"foo": "bar",
"zip": "zap"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/my-secret
```
## Recover secret
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
| Method | Path |
| :----- | :------------------------------------------------------- |
| `POST` | `/secret/:path?recover_snapshot_id=:recover_snapshot_id` |
### Query parameters
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://127.0.0.1:8200/v1/secret/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
```
## Delete secret
This endpoint deletes the secret at the specified location.
| Method | Path |
| :------- | :-------------- |
| `DELETE` | `/secret/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/secret/my-secret
```

761
website/content/api-docs/secret/kv/kv-v2.mdx
View file

@ -1,761 +0,0 @@
---
layout: api
page_title: KV - Secrets Engines - HTTP API
description: This is the API documentation for the Vault KV secrets engine, version 2.
---
> [!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.
# KV secrets engine - version 2 (API)
This is the API documentation for the Vault KV secrets engine while running in
versioned mode. For general information about the usage and operation of the version 2
KV secrets engine, please see the [Vault KV documentation](/vault/docs/secrets/kv/kv-v2).
For information about the differences between KV version 1 and version 2, please [see the KV overview
documentation](/vault/docs/secrets/kv).
## Configure the KV engine
This path configures backend level settings that are applied to every key in the
key-value store.
| Method | Path |
|:-------|:-----------------------------|
| `POST` | `/:secret-mount-path/config` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount to config,
such as `secret`. This is specified as part of the URL.
- `max_versions` `(int: 0)` – The number of versions to keep per key. This value
applies to all keys, but a key's metadata setting can overwrite this value.
Once a key has more than the configured allowed versions, the oldest version
will be permanently deleted. When 0 is used or the value is unset, Vault
will keep 10 versions.
- `cas_required` `(bool: false)` – If true all keys will require the cas
parameter to be set on all write requests.
- `delete_version_after` `(string:"0s")` – If set, specifies the length
of time before a version is deleted.
Accepts [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"max_versions": 5,
"cas_required": false,
"delete_version_after": "3h25m19s"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/config
```
## Read KV engine configuration
This path retrieves the current configuration for the secrets backend at the
given path.
| Method | Path |
|:-------|:-----------------------------|
| `GET` | `/:secret-mount-path/config` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount to read the config,
of, such as `secret`. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/config
```
### Sample response
```json
{
"data": {
"cas_required": false,
"delete_version_after": "3h25m19s",
"max_versions": 0
}
}
```
## Read secret version
This endpoint retrieves the secret at the specified location. The metadata
fields `created_time`, `deletion_time`, `destroyed`, and `version` are version
specific. The `custom_metadata` field is part of the secret's key metadata and
is included in the response whether or not the calling token has `read` access to
the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata).
| Method | Path |
|:-------|:---------------------------------------------------------|
| `GET` | `/:secret-mount-path/data/:path?version=:version-number` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL.
- `version` `(int: 0)` - Specifies the version to return. If not set the latest
version is returned.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/data/my-secret?version=2
```
### Sample response
```json
{
"data": {
"data": {
"foo": "bar"
},
"metadata": {
"created_time": "2018-03-22T02:24:06.945319214Z",
"custom_metadata": {
"owner": "jdoe",
"mission_critical": "false"
},
"deletion_time": "",
"destroyed": false,
"version": 2
}
}
}
```
## Create/Update secret
This endpoint creates a new version of a secret at the specified location. If
the value does not yet exist, the calling token must have an ACL policy granting
the `create` capability. If the value already exists, the calling token must
have an ACL policy granting the `update` capability.
| Method | Path |
|:-------|:---------------------------------|
| `POST` | `/:secret-mount-path/data/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to update, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to update.
This is specified as part of the URL.
- `options` `(Map: <optional>)` – An object that holds option settings.
- `cas` `(int: <optional>)` - This flag is required if `cas_required` is set
to true on either the secret or the engine's config. If not set the write
will be allowed. In order for a write to be successful, `cas` must be set to
the current version of the secret. If set to 0 a write will only be allowed if
the key doesn't exist as unset keys do not have any version information. Also
remember that soft deletes do not remove any underlying version data from storage.
In order to write to a soft deleted key, the cas parameter must match the key's
current version.
- `data` `(Map: <required>)` – The contents of the data map will be stored and
returned on read.
### Sample payload
```json
{
"options": {
"cas": 0
},
"data": {
"foo": "bar",
"zip": "zap"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/data/my-secret
```
### Sample response
```json
{
"data": {
"created_time": "2018-03-22T02:36:43.986212308Z",
"custom_metadata": {
"owner": "jdoe",
"mission_critical": "false"
},
"deletion_time": "",
"destroyed": false,
"version": 1
}
}
```
## Patch secret
This endpoint provides the ability to patch an _existing_ secret at the specified
location. The secret must neither be deleted nor destroyed. The calling token must
have an ACL policy granting the `patch` capability. Currently, only
[JSON merge patch](https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-merge-patch-07)
is supported and must be specified using a `Content-Type` header value of
`application/merge-patch+json`. A new version will be created upon successfully
applying a patch with the provided data.
| Method | Path |
|:--------|:---------------------------------|
| `PATCH` | `/:secret-mount-path/data/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to patch, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to patch.
This is specified as part of the URL.
- `options` `(Map: <optional>)` – An object that holds option settings.
- `cas` `(int: <optional>)` - This flag is required if `cas_required` is set to true on either
the secret or the engine's config. In order for a write to be successful, `cas` must be set
to the current version of the secret. A patch operation must be attempted on an existing
key, thus the provided `cas` value must be greater than 0.
- `data` `(Map: <required>)` – The contents of the data map will be applied as a partial
update to the existing entry via a JSON merge patch to the existing entry.
### Sample payload
```json
{
"options": {
"cas": 1
},
"data": {
"foo": "a",
"bar": {
"baz": "b"
}
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--header "Content-Type: application/merge-patch+json"
--request PATCH \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/data/my-secret
```
### Sample response
```json
{
"data": {
"created_time": "2021-09-10T15:26:08.684999Z",
"custom_metadata": {
"owner": "jdoe",
"mission_critical": "false"
},
"deletion_time": "",
"destroyed": false,
"version": 2
}
}
```
## Read secret subkeys
This endpoint provides the subkeys within a secret entry that exists
at the requested path. The secret entry at this path will be retrieved
and stripped of all data by replacing underlying values of leaf keys
(i.e. non-map keys or map keys with no underlying subkeys) with `null`.
| Method | Path |
|:-------|:------------------------------------|
| `GET` | `/:secret-mount-path/subkeys/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL.
- `version` `(int: 0)` - Specifies the version to return. If not set the latest
version is returned.
- `depth` `(int: 0)` - Specifies the deepest nesting level to provide in the output.
The default value 0 will not impose any limit. If non-zero, keys that reside at the
specified `depth` value will be artificially treated as leaves and will thus be `null`
even if further underlying subkeys exist.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/subkeys/my-secret?version=1
```
### Sample secret data
```json
{
"foo": "abc",
"bar": {
"baz": "def"
},
"quux": {}
}
```
### Sample response
```json
{
"subkeys": {
"foo": null,
"bar": {
"baz": null
},
"quux": null
},
"metadata": {
"created_time": "2021-12-14T20:28:00.773477Z",
"custom_metadata": null,
"deletion_time": "",
"destroyed": false,
"version": 1
}
}
```
## Delete latest version of secret
This endpoint issues a soft delete of the secret's latest version at the
specified location. This marks the version as deleted and will stop it from
being returned from reads, but the underlying data will not be removed. A
delete can be undone using the `undelete` path.
| Method | Path |
| :------- | :------------------- |
| `DELETE` | `/:secret-mount-path/data/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/secret/data/my-secret
```
## Delete secret versions
This endpoint issues a soft delete of the specified versions of the secret. This
marks the versions as deleted and will stop them from being returned from reads,
but the underlying data will not be removed. A delete can be undone using the
`undelete` path.
| Method | Path |
|:-------|:-----------------------------------|
| `POST` | `/:secret-mount-path/delete/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL.
- `versions` `([]int: <required>)` - The versions to be deleted. The versioned
data will not be deleted, but it will no longer be returned in normal get
requests.
### Sample payload
```json
{
"versions": [1, 2]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/delete/my-secret
```
## Undelete secret versions
Undeletes the data for the provided version and path in the key-value store.
This restores the data, allowing it to be returned on get requests.
| Method | Path |
|:-------|:-------------------------------------|
| `POST` | `/:secret-mount-path/undelete/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to undelete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to undelete.
This is specified as part of the URL.
- `versions` `([]int: <required>)` - The versions to undelete. The versions will
be restored and their data will be returned on normal get requests.
### Sample payload
```json
{
"versions": [1, 2]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/undelete/my-secret
```
## Destroy secret versions
Permanently removes the specified version data for the provided key and version
numbers from the key-value store.
| Method | Path |
|:-------|:------------------------------------|
| `PUT` | `/:secret-mount-path/destroy/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to destroy, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to destroy.
This is specified as part of the URL.
- `versions` `([]int: <required>)` - The versions to destroy. Their data will be
permanently deleted.
### Sample payload
```json
{
"versions": [1, 2]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request PUT \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/destroy/my-secret
```
## List secrets
This endpoint returns a list of key names at the specified location. Folders are
suffixed with `/`. The input must be a folder; list on a file will not return a
value. Note that no policy-based filtering is performed on keys; do not encode
sensitive information in key names. The values themselves are not accessible via
this command.
To list secrets for KV v2, a user must have a policy granting them the list capability on this `/metadata/` path - even if all the rest of their interactions with the KV v2 are via the `/data/` APIs. Access to at least list the `/metadata/` path should typically also be granted.
| Method | Path |
|:-------|:-------------------------------------|
| `LIST` | `/:secret-mount-path/metadata/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to list, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/secret/metadata/my-secret
```
### Sample response
The example below shows output for a query path of `secret/` when there are
secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two
entries.
```json
{
"data": {
"keys": ["foo", "foo/"]
}
}
```
## Read secret metadata
This endpoint retrieves the metadata and versions for the secret at the
specified path. Metadata is version-agnostic.
| Method | Path |
|:-------|:-------------------------------------|
| `GET` | `/:secret-mount-path/metadata/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/secret/metadata/my-secret
```
### Sample response
```json
{
"data": {
"cas_required": false,
"created_time": "2018-03-22T02:24:06.945319214Z",
"current_version": 3,
"delete_version_after": "3h25m19s",
"max_versions": 0,
"oldest_version": 0,
"updated_time": "2018-03-22T02:36:43.986212308Z",
"custom_metadata": {
"foo": "abc",
"bar": "123",
"baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
},
"versions": {
"1": {
"created_time": "2018-03-22T02:24:06.945319214Z",
"deletion_time": "",
"destroyed": false
},
"2": {
"created_time": "2018-03-22T02:36:33.954880664Z",
"deletion_time": "",
"destroyed": false
},
"3": {
"created_time": "2018-03-22T02:36:43.986212308Z",
"deletion_time": "",
"destroyed": false
}
}
}
}
```
## Create/Update metadata
This endpoint creates or updates the metadata of a secret at the specified location.
It does not create a new version.
| Method | Path |
|:-------|:-------------------------------------|
| `POST` | `/:secret-mount-path/metadata/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to update, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to update.
This is specified as part of the URL.
- `max_versions` `(int: 0)` – The number of versions to keep per key. If not
set, the backend’s configured max version is used. Once a key has more than
the configured allowed versions, the oldest version will be permanently
deleted.
- `cas_required` `(bool: false)` – If true, the key will require the `cas`
parameter to be set on all write requests. If false, the backend’s
configuration will be used.
- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value
to a duration to specify the `deletion_time` for all new versions
written to this key. If not set, the backend's `delete_version_after` will be
used. If the value is greater than the backend's `delete_version_after`, the
backend's `delete_version_after` will be used. Accepts [duration format
strings](/vault/docs/concepts/duration-format).
- `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant
to describe the secret.
### Sample payload
```json
{
"max_versions": 5,
"cas_required": false,
"delete_version_after": "3h25m19s",
"custom_metadata": {
"foo": "abc",
"bar": "123",
"baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/metadata/my-secret
```
## Patch metadata
This endpoint patches an existing metadata entry of a secret at the specified
location. The calling token must have an ACL policy granting the `patch`
capability. Currently, only JSON merge patch is supported and must be specified
using a `Content-Type` header value of `application/merge-patch+json`. It does
not create a new version.
| Method | Path |
|:--------|:-------------------------------------|
| `PATCH` | `/:secret-mount-path/metadata/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to patch, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to patch.
This is specified as part of the URL.
- `max_versions` `(int: 0)` – The number of versions to keep per key. If not
set, the backend’s configured max version is used. Once a key has more than
the configured allowed versions, the oldest version will be permanently
deleted.
- `cas_required` `(bool: false)` – If true, the key will require the `cas`
parameter to be set on all write requests. If false, the backend’s
configuration will be used.
- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value
to a duration to specify the `deletion_time` for all new versions
written to this key. If not set, the backend's `delete_version_after` will be
used. If the value is greater than the backend's `delete_version_after`, the
backend's `delete_version_after` will be used. Accepts [duration format
strings](/vault/docs/concepts/duration-format).
- `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant
to describe the secret.
### Sample payload
```json
{
"max_versions": 5,
"custom_metadata": {
"bar": "123"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--header "Content-Type: application/merge-patch+json"
--request PATCH \
--data @payload.json \
https://127.0.0.1:8200/v1/secret/metadata/my-secret
```
## Delete metadata and all versions
This endpoint permanently deletes the key metadata and all version data for the
specified key. All version history will be removed.
| Method | Path |
|:---------|:-------------------------|
| `DELETE` | `/:secret-mount-path/metadata/:path` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/secret/metadata/my-secret
```

875
website/content/api-docs/secret/ldap.mdx
View file

@ -1,875 +0,0 @@
---
layout: api
page_title: LDAP - Secrets Engines - HTTP API
description: This is the API documentation for the Vault LDAP secrets engine.
---
> [!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.
# LDAP secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault LDAP secrets engine. For general
information about the usage and operation of the LDAP secrets engine,
please see the [LDAP secrets engine docs](/vault/docs/secrets/ldap).
This documentation assumes the LDAP secrets engine is enabled at the `/ldap` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.
## Configuration management
This endpoint configures the LDAP secret engine to manage user entries.
| Method | Path |
| :------- | :----------------- |
| `POST` | `/ldap/config` |
| `GET` | `/ldap/config` |
| `DELETE` | `/ldap/config` |
-> **Note**: The LDAP entry used by `config` should have the necessary privileges
to search and change entry passwords in LDAP.
### Parameters
- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.
For example, `cn=vault,ou=Users,dc=hashicorp,dc=com`.
- `bindpass` `(string: <required>)` - Password to use along with `binddn` for managing user entries.
- `url` `(string: "ldap://127.0.0.1")` - The LDAP server to connect to. Examples: `ldaps://ldap.myorg.com`,
`ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g.
`ldaps://ldap.myorg.com, ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if
there are errors during the connection process.`.
- `password_policy` `(string: <optional>)` - The name of the [password policy](/vault/docs/concepts/password-policies)
to use to generate passwords. Note that this accepts the name of the policy, not the policy itself.
- `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords.
Valid schemas include `openldap`, `ad`, and `racf`.
- `userdn` `(string: <optional>)` - The base DN under which to perform user search in
[library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles).
For example, `ou=Users,dc=hashicorp,dc=com`.
- `userattr` `(string: <optional>)` – The attribute field name used to perform user search
in [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles).
Defaults to `cn` for the `openldap` schema, `userPrincipalName` for the `ad` schema, and
`racfid` for the `racf` schema.
- `upndomain` (string: `optional`) - The domain (userPrincipalDomain) used to construct a UPN
string for authentication. The constructed UPN will appear as `[binddn]@[upndomain]`. For
example, if `upndomain=example.com` and `binddn=admin`, the UPN string `admin@example.com`
will be used to log in to Active Directory.
- `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when
making requests against the server before returning back an error.
- `starttls` `(bool: <optional>)` - If true, issues a `StartTLS` command after establishing an unencrypted connection.
- `insecure_tls` `(bool: <optional>)` - If true, skips LDAP server SSL certificate verification - insecure,
use with caution!
- `certificate` `(string: <optional>)` - CA certificate to use when verifying LDAP server certificate, must be
x509 PEM encoded.
- `client_tls_cert` `(string: <optional>)` - Client certificate to provide to the LDAP server, must be x509
PEM encoded.
- `client_tls_key` `(string: <optional>)` - Client key to provide to the LDAP server, must be x509 PEM encoded.
- `skip_static_role_import_rotation` `(bool: false)` - The default value to use for `skip_import_rotation` when
creating static roles. This field can be overridden on an individual role level during [role creation](#static-roles).
See the [static roles section](#static-roles) for more detailed information and caveats.
@include 'rotationfields.mdx'
**Deprecated Parameters**:
- `length` `(int: 64)` - The length of generated password strings. Note: some schemas may require shorter
password lengths (such as `racf`). Mutually exclusive with `password_policy`
- `connection_timeout` `(integer: 30 or string: "30s")` - Timeout, in
seconds, before trying the next URL in your Vault configuration when
attempting to connect to your LDAP server. When both
`connection_timeout` and `request_timeout` are set, Vault uses the
smaller of the two values for connection **and** request timeouts.
**Note about password generation**:
`length` and `password_policy` cannot both be set in the configuration. The `POST` endpoint will reject the
configuration if both are specified.
- If neither are set, this will default to a reasonable default password generation algorithm (the same algorithm as
prior to the introduction of password policies).
- If `length` is set, the same algorithm is used, but with the length specified instead of the default length.
- If `password_policy` is set, the password will be generated from the associated
[password policy](/vault/docs/concepts/password-policies). The policy is not exercised prior to saving the configuration.
The policy will need to exist prior to passwords needing to be generated by this engine, but does not need to exist
prior to saving the configuration.
See [LDAP secrets engine docs](/vault/docs/secrets/ldap) for additional information.
### Sample payload
```json
{
"binddn": "cn=vault,ou=Users,dc=hashicorp,dc=com",
"bindpass": "pa$$w0rd",
"url": "ldaps://127.0.0.11"
}
```
### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/config
```
### Sample GET request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/ldap/config
```
### Sample response
```json
{
"data": {
"binddn": "cn=admin,dc=hashicorp,dc=com",
"case_sensitive_names": false,
"certificate": "",
"insecure_tls": false,
"length": 64,
"schema": "openldap",
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"url": "ldap://127.0.0.1"
}
}
```
## Rotate root password
The `rotate-root` endpoint offers password rotation for the `binddn` entry used to manage LDAP.
This generated password will only be known to Vault and will not be retrievable once rotated.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/ldap/rotate-root` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/ldap/rotate-root
```
## Static roles
The `static-role` endpoint configures Vault to manage the passwords of existing individual LDAP entries.
| Method | Path |
| :------- | :--------------------------------- |
| `GET` | `/ldap/static-role` |
| `GET` | `/ldap/static-role/:role_name` |
| `LIST` | `/ldap/static-role/:role_name` |
| `POST` | `/ldap/static-role/:role_name` |
| `DELETE` | `/ldap/static-role/:role_name` |
<Note>
Windows Servers hosting Active Directory include a
`lifetime period of an old password` configuration setting that lets clients
authenticate with old passwords for a specified amount of time.
For more information, refer to the
[NTLM network authentication behavior](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/new-setting-modifies-ntlm-network-authentication)
guide by Microsoft.
</Note>
### Parameters
- `role_name` `(string: <required>)` – URL parameter specifying the name of the
role. Role name can contain an arbitrary number of forward slashes to define a
[hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
- `username` `(string: <required>)` - The username of the existing LDAP entry to manage
password rotation for. LDAP search for the username will be rooted at the [userdn](/vault/api-docs/secret/ldap#userdn)
configuration value. The attribute to use when searching for the user can be configured
with the [userattr](/vault/api-docs/secret/ldap#userattr) configuration value. This is useful
when `dn` isn't used for login purposes (such as SSH). Cannot be modified after creation.<br />
**Example:** `"bob"`
- `dn` `(string: <optional>)` - Distinguished name (DN) of the existing LDAP entry to manage
password rotation for. If given, it will take precedence over `username` for the LDAP
search performed during password rotation. Cannot be modified after creation.<br />
**Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com`
- `rotation_period` `(string: <required>)` - How often Vault should rotate the password of the user entry. Accepts
[duration format strings](/vault/docs/concepts/duration-format). The minimum rotation period is 5 seconds.<br />
**Example:** `"3600", "5s", "1h"`
- `skip_import_rotation` `(boolean: false)` - When set on a role creation request, Vault will not rotate the
pre-existing password of the associated LDAP entry. Note: This means that Vault will not be able to supply the
password to `GET` requests until the password is rotated (either automatically or manually by `rotate-role`). This
field overrides `skip_static_role_import_rotation` from the ldap config if both are set.
### Sample payload
```json
{
"dn": "cn=hashicorp,ou=Users,dc=hashicorp,dc=com",
"rotation_period": "24h",
"username": "hashicorp"
}
```
### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/static-role/hashicorp
```
### Sample GET request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/ldap/static-role/hashicorp
```
### Sample GET response
```json
{
"data": {
"dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
"last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
"rotation_period": 86400,
"username": "hashicorp"
}
}
```
### Sample LIST response
```json
["hashicorp", "bob"]
```
## Static role passwords
The `static-cred` endpoint offers the credential information for a given static-role.
| Method | Path |
| :----- | :--------------------------------- |
| `GET` | `/ldap/static-cred/:role_name` |
### Parameters
- `role_name` `(string: <required>)` – URL parameter specifying the name of the
role.
#### Sample GET request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/ldap/static-cred/hashicorp
```
#### Sample GET response
```json
{
"dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
"last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
"password": "LTNfyn7pS7XEZIxEYQ2sEAWic02PEP7zSvIs0xMqIjaU0ORzLhKOKVmYLxL1Xkyv",
"last_password": "?@09AZSen9TzUwK7ZhafS7B0GuWGraQjfWEna5SwnmF/tVaKFqjXhhGV/Z0v/pBJ",
"rotation_period": 86400,
"ttl": 86072,
"username": "hashicorp"
}
```
## Manually rotate static role password
The `rotate-role` endpoint rotates the password of an existing static role.
| Method | Path |
| :----- | :--------------------------------- |
| `POST` | `/ldap/rotate-role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` – URL parameter specifying the name of the
role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/ldap/rotate-role/:role_name
```
## Dynamic roles
Create or update a dynamic role configuration. This provides instructions to Vault on how to create an
LDAP domain user account.
### Create/Delete dynamic role configuration
Creates, updates, or deletes a dynamic role.
| Method | Path |
| :------- | :-------------------------- |
| `GET` | `/ldap/role/:role_name` |
| `POST` | `/ldap/role/:role_name` |
| `DELETE` | `/ldap/role/:role_name` |
The `POST` endpoint allows for partial updates of existing roles. If a role exists and a `POST` request is made
against it, only the keys specified in the request will be updated. To delete a value, specify the key with an
empty string as the value. Example: `vault write ldap/role/myrole default_ttl=""`
#### Parameters
- `role_name` `(string: <required>)` – URL parameter specifying the name of the
role. Role name can contain an arbitrary number of forward slashes to define a
[hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
- `creation_ldif` `(string, required)` - A templatized LDIF string used to create a user account. This may contain
multiple LDIF entries. The `creation_ldif` can also be used to add the user account to an **_existing_** group.
All LDIF entries are performed in order. If Vault encounters an error while executing the `creation_ldif` it will
stop at the first error and not execute any remaining LDIF entries. If an error occurs and `rollback_ldif` is
specified, the LDIF entries in `rollback_ldif` will be executed. See `rollback_ldif` for more details. This field
may optionally be provided as a base64 encoded string.
- `deletion_ldif` `(string, required)` - A templatized LDIF string used to delete the user account once its TTL has
expired. This may contain multiple LDIF entries. All LDIF entries are performed in order. If Vault encounters an
error while executing an entry in the `deletion_ldif` it will attempt to continue executing any remaining entries.
This field may optionally be provided as a base64 encoded string.
- `rollback_ldif` `(string, not required but recommended)` - A templatized LDIF string used to attempt to rollback
any changes in the event that execution of the `creation_ldif` results in an error. This may contain multiple LDIF
entries. All LDIF entries are performed in order. If Vault encounters an error while executing an entry in the
`rollback_ldif` it will attempt to continue executing any remaining entries. This field may optionally be provided
as a base64 encoded string.
- `username_template` `(string)` - A template used to generate a dynamic username. This will be used to fill in the
`.Username` field within the `creation_ldif` string.
<details>
<summary><b>Default Username Template</b></summary>
```
v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}
```
<details>
<summary><b>Example Usernames:</b></summary>
| Example | |
| ------------- | ------------------------------------------ |
| `DisplayName` | `token` |
| `RoleName` | `myrolename` |
| Username | `v_token_myrolename_uszt1n4cyh_1614294836` |
| Example | |
| ------------- | -------------------------------------------------------------------- |
| `DisplayName` | `amuchlonger_dispname` |
| `RoleName` | `role-name-with-dashes` |
| Username | `v_amuchlonger_dispname_role-name-with-dashes_s0t9xb0jsa_1614294836` |
</details>
</details>
- `default_ttl` `(string/int)` - Specifies the TTL for the leases associated with this role. Accepts
[duration format strings](/vault/docs/concepts/duration-format). Defaults to system/engine default TTL time.
- `max_ttl` `(string/int)` - Specifies the maximum TTL for the leases associated with this role. Accepts
[duration format strings](/vault/docs/concepts/duration-format). Defaults to system/mount default TTL time;
this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL),
but it is not allowed to be longer.
The `creation_ldif`, `deletion_ldif`, `rollback_ldif`, and `username_template` fields are all templated fields. See
[Username Templating](/vault/docs/concepts/username-templating) for details on how to use templating. Also see
[Templates](#templates) for specifics on what data is available for each template.
#### Sample payload
Sample LDIF files:
`creation.ldif`:
```
dn: cn={{.Username}},ou=users,dc=learn,dc=example
objectClass: person
objectClass: top
cn: learn
sn: {{.Password | utf16le | base64}}
memberOf: cn=dev,ou=groups,dc=learn,dc=example
userPassword: {{.Password}}
```
`deletion.ldif` & `rollback.ldif`:
```
dn: cn={{.Username}},ou=users,dc=learn,dc=example
changetype: delete
```
Full Payload:
```json
{
"creation_ldif": "...",
"deletion_ldif": "...",
"rollback_ldif": "...",
"username_template": "...",
"default_ttl": "1h",
"max_ttl": "24h"
}
```
-> Note: The LDIF statements may optionally be base64 encoded. If they are base64 encoded when creating/updating the
role configuration, the decoded version will be returned from the `GET` endpoint.
#### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/role/dynamic-role
```
### Templates
LDIF and username templates use the [Go template syntax](https://golang.org/pkg/text/template/) to construct the
LDIF/username that will be executed against the server. This is done because certain values (such as the username
and password within an LDIF statement) are not known at configuration time. Additionally, the template gives a
lot of flexibility to the operator to construct the LDIF and username.
Templated fields are delimited by `{{` and `}}`. To reference a field (such as the generated `Username`), a period is
placed in front of the field name. Example: `{{.Username}}`. Spaces can be included between `{{` and `}}`. For instance:
`{{.Username|lowercase}}` is the same as `{{ .Username | lowercase }}`.
If a field needs to be modified (such as SHA256 hashing, base64 encoding, etc.) the value can be sent to one of the
[built-in functions](#template-functions). This uses a "pipe" syntax: `{{.Username | base64}}`. Values may be "piped"
to multiple functions: `{{.Username | lowercase | base64}}`
#### LDIF template fields
The following parameters are available within the LDIF templates:
`.Username` - The name of the generated user (optionally from `username_template`).<br />
**Default pattern:** `v_<display name>_<role name>_<10 random chars>_<unix timestamp>`
`.Password` - The generated password (optionally from
[password policies](/vault/docs/concepts/password-policies))
`.RoleName` - The name of the role that credentials are being generated for.
`.DisplayName` - The display name associated with the authentication token used to make the credentials request.
`.IssueTime` - The time that the lease was created. This time may be slightly earlier than the associated lease due to
where this value is calculated compared with where Vault calculates details of the lease.<br />
**Format:** 2006-01-02T15:04:05Z07:00 ([RFC3339](https://golang.org/pkg/time/#pkg-constants))
`.IssueTimeSeconds` - The [unix time](https://en.wikipedia.org/wiki/Unix_time) the lease was created. This time may
be slightly earlier than the associated lease due to where this value is calculated compared with where Vault
calculates details of the lease.<br />
**Format:** Integer indicating the number of seconds elapsed since January 1, 1970.
`.ExpirationTime` - The time that the lease is set to expire. This time may be slightly earlier than the associated
lease due to where this value is calculated compared with where Vault calculates details of the lease.<br />
**Format:** 2006-01-02T15:04:05Z07:00 ([RFC3339](https://golang.org/pkg/time/#pkg-constants))
`.ExpirationTimeSeconds` - The [unix time](https://en.wikipedia.org/wiki/Unix_time) the lease is set to expire. This
time may be slightly earlier than the associated lease due to where this value is calculated compared with where Vault
calculates details of the lease.<br />
**Format:** Integer indicating the number of seconds elapsed since January 1, 1970.
#### Username template fields
The following parameters are available within the username template:
**Important note:** If any of the following fields include dashes or underscores, they will not be removed/changed
unless explicitly done so within the username template. For instance:
If `RoleName` is `test-role` and the `username_template` is `v_{{.RoleName}}_{{unix_time}}`, the result of this template
may be: `v_test-role_1234567890`. Note the `-` (dash) in the `test-role`. If the LDAP system Vault is managing
restricts usernames/DNs to not allow for dashes (or other characters), the template must explicitly modify/remove those
characters. In this example, the template can be changed to `v_{{.RoleName | replace "-" "_"}}` to replace
the dashes with underscores. See [Template Functions](#template-functions) for more functions available.
`.RoleName` - The name of the role the credentials are being generated from.
`.DisplayName` - The display name associated with the user making the request against Value.
#### Template functions
Both the LDIF templates and the username template use the [Go template language](https://golang.org/pkg/text/template)
so all [functions](https://golang.org/pkg/text/template/#hdr-Functions) and capabilities from that language are
supported including functions such as `printf`.
In addition to the functions available through the template language, the following custom functions are also available:
`random` - Generates a random string from lowercase letters, uppercase letters, and numbers. Must include a
number indicating how many characters to generate.<br />
**Example:** `{{random 20}}` generates 20 random characters
`truncate` - truncates the previous value to the provided number of characters.<br />
**Example:** `{{.FieldName | truncate 10}}`
`truncate_sha256` - Truncates the previous value to the provided number of characters. The last 8 characters of the
truncated value will be the first 8 characters of the SHA256 hash of the truncated characters.
This can aid in identifying values (such as the role & display names) if they need to be truncated to a particular
length, particularly if the value has common prefixes. An example of this is having many roles with a common prefix in
the name of the role, but the role name is truncated such that only the prefix is shown. This function will keep the
non-prefix part of the role name in the username which will aid in identification while also keeping uniqueness.
**Example:**<br />
`v_{{.RoleName | truncate_sha256 15}}_{{unix_time}}`. <br />
If two roles exist for this template, `myreallylongprefix-foobar` and `myreallylongprefix-bazqux`, the username for the first role
would be `v_myrealle6da86ec_1234567890` and the username for the second role would be `v_myrealld0420a55_1234567890`.
`uppercase` - Uppercases the provided value.<br />
**Example:** `{{.FieldName | uppercase}}`
`lowercase` - Lowercases the provided value.<br />
**Example:** `{{.FieldName | lowercase}}`
`replace` - Find/replace on the provided value.<br />
**Example:** `{{.FieldName | replace "-" "_"}}`
`sha256` - SHA256 hashes the provided value.<br />
**Example:** `{{.FieldName | sha256}}`
`base64` - Base64 encodes the provided value.<br />
**Example:** `{{.FieldName | base64}}`
`unix_time` - The current unix timestamp (number of seconds since Jan 1 1970).<br />
**Example:** `{{unix_time}}`
`unix_time_millis` - The current unix timestamp in milliseconds.<br />
**Example:** `{{unix_time_millis}}`
`timestamp` - The current time. Must provide a formatting string based on Go’s time package.<br />
**Example:** `{{timestamp "2006-01-02T15:04:05Z"}}`
`uuid` - Generates a random UUID.<br />
**Example:** `{{uuid}}`
##### LDIF template functions
Additionally, the LDIF templates include an additional function to facilitate Active Directory password handling.
The username template cannot use this function.
`utf16le` - Encodes the provided value into UTF16-LE.<br />
**Example:** `{{.FieldName | utf16le}}`
## Dynamic role passwords
The `creds` endpoint offers the credential information for a given dynamic role.
| Method | Path |
| :----- | :--------------------------------- |
| `GET` | `/ldap/creds/:role_name` |
### Parameters
- `role_name` `(string: <required>)` – URL parameter specifying the name of the
role.
#### Sample GET request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/ldap/creds/dynamic-role
```
#### Sample GET response
```json
{
"distinguished_names": [
"cn=v_token-dispname_testrole_jmZMnjS42a_1680580467,ou=users,dc=hashicorp,dc=com"
],
"password": "OWexB3OzYYLFiotWxUS2EheGpriwR20fa2yA7JGTsnBREcxyqpwf73htofMihxcC",
"username": "v_token-dispname_testrole_jmZMnjS42a_1680580467"
}
```
## Library set management
The `library` endpoint configures the sets of service accounts that Vault will offer for check-out.
| Method | Path |
| :------- | :---------------------- |
| `LIST` | `/ldap/library` |
| `LIST` | `/ldap/library/:set_name` |
| `POST` | `/ldap/library/:set_name` |
| `GET` | `/ldap/library/:set_name` |
| `DELETE` | `/ldap/library/:set_name` |
When adding a service account to the library, Vault verifies it already exists in the LDAP directory.
### Parameters
- `set_name` `(string: <required>)` – URL parameter specifying the name of the
set.
- `service_account_names` `(string: "", or list: [] required)` - The names of all the service accounts that can be
checked out from this set. These service accounts must only be used by Vault, and may only be in one set. These
service accounts must already exist in the LDAP directory.
- `ttl` `(duration: "24h", optional)` - The maximum amount of time a single check-out lasts before Vault
automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period.
Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_ttl` `(duration: "24h", optional)` - The maximum amount of time a check-out last with renewal before Vault
automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period.
Uses [duration format strings](/vault/docs/concepts/duration-format).
- `disable_check_in_enforcement` `(bool: false, optional)` - Disable enforcing that service accounts must be
checked in by the entity or client token that checked them out. Defaults to false.
### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team
```
### Sample POST payload
```json
{
"service_account_names": ["fizz@example.com", "buzz@example.com"],
"ttl": "10h",
"max_ttl": "20h",
"disable_check_in_enforcement": false
}
```
### Sample GET response
```json
{
"service_account_names": ["fizz@example.com", "buzz@example.com"],
"ttl": "10h",
"max_ttl": "20h",
"disable_check_in_enforcement": false
}
```
### Sample LIST request
Use the `/ldap/library` endpoint to list the top-level set names of service
accounts in Vault. Refer to the LDAP secrets engine
[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation
for more information on path-based names.
For example:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/ldap/library
```
#### Sample LIST response
```json
["accounting-team", "dev/"]
```
### Sample LIST request
Use the `/ldap/library` endpoint to list the top-level set names of service
accounts in Vault at the given path. Refer to the LDAP secrets engine
[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation
for more information on path-based names.
For example:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/ldap/library/dev
```
#### Sample LIST response
```json
["backend", "frontend"]
```
## Library set status check
This endpoint provides the check-out status of service accounts in a library set.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/ldap/library/:set_name/status` |
### Parameters
- `set_name` `(string: "", required)` - URL parameter specifying the set name of
the requested service accounts. The set name can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
### Sample GET request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/status
```
### Sample GET response
```json
{
"request_id": "9e44c8b5-d142-5867-2a11-49f3ba71215a",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"buzz@example.com": {
"available": true
},
"fizz@example.com": {
"available": false,
"borrower_client_token": "4c653e473bf7e27c6759fccc3def20c44d776279",
"borrower_entity_id": "631256b1-8523-9838-5501-d0a1e2cdad9c"
}
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Check-Out management
This endpoint provides service account check out for a library set.
| Method | Path |
| :----- | :-------------------------------- |
| `POST` | `/ldap/library/:set_name/check-out` |
Returns a `200` if a credential is available, and a `400` if no credential is available.
### Parameters
- `set_name` `(string: "", required)` - URL parameter specifying the set name of
the requested service accounts. The set name can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
- `ttl` `(duration: "", optional)` - The maximum amount of time a check-out lasts before Vault
automatically checks it back in. Setting it to zero reflects an unlimited lending period.
Defaults to the set's `ttl`. If the requested `ttl` is higher than the set's, the set's will be used.
Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-out
```
### Sample POST payload
```json
{
"ttl": "1h"
}
```
### Sample POST response
```json
{
"request_id": "364a17d4-e5ab-998b-ceee-b49929229e0c",
"lease_id": "ad/library/accounting-team/check-out/aoBsaBEI4PK96VnukubvYDlZ",
"renewable": true,
"lease_duration": 36000,
"data": {
"password": "?@09QW0KZ8DSBu3deIu7XLY1NZqzwhozmMAZ6v0IcZJGOjs5GvpVMvOeW7/duls2",
"service_account_name": "fizz@example.com"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Check-In management
By default, check-in must be called by the same entity or client token used for check-out.
To disable this behavior, use the `disable_check_in_enforcement` toggle on the library set. Or, use
the `ad/library/manage/:set_name/check-in` behavior to force check-in of the account. Access to the
"manage" endpoint should only be granted to highly privileged Vault users, like Vault operators.
If a caller attempts to check in a service account they're not authorized to check in, they will
receive an error response. If they attempt to check in a service account they _are_ authorized to
check in, but it's _already_ checked in, they will receive a successful response but the account
will not be included in the `check_ins` listed. `check_ins` shows which service accounts were checked
in _by this particular call_.
| Method | Path |
| :----- | :-------------------------------------- |
| `POST` | `/ldap/library/:set_name/check-in` |
| `POST` | `/ldap/library/manage/:set_name/check-in` |
### Parameters
- `set_name` `(string: "", required)` - URL parameter specifying the set name of
the requested service accounts. The set name can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
- `service_account_names` `(string: "", or list: [] optional)` - The names of all the service accounts to be
checked in. May be omitted if only one is checked out.
### Sample POST request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-in
```
### Sample POST payload
```json
{
"service_account_names": ["fizz@example.com"]
}
```
### Sample POST response
```json
{
"request_id": "db45c714-3f68-b748-95bc-8f7467637a52",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"check_ins": ["fizz@example.com"]
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```

257
website/content/api-docs/secret/mongodbatlas.mdx
View file

@ -1,257 +0,0 @@
---
layout: api
page_title: MongoDB Atlas - Secrets Engines - HTTP API
description: |-
The MongoDB Atlas Secrets Engine for Vault generates MongoDB Atlas Programmatic API Keys dynamically.
---
> [!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.
# MongoDB atlas secrets engine
The MongoDB Atlas Secrets Engine generates Programmatic API keys for MongoDB Atlas. This allows one to manage the lifecycle of these MongoDB Atlas secrets through Vault. The created MongoDB Atlas secrets are
time-based and are automatically revoked when the Vault lease expires, unless renewed. Vault will create a Programmatic API key for each lease scoped to the MongoDB Atlas project or organization denoted with the included role(s). An IP Whitelist may also be configured for the Programmatic API key with desired IPs and/or CIDR blocks.
The MongoDB Atlas Programmatic API Key Public and
Private Key is returned to the caller. To learn more about Programmatic API Keys visit the [Programmatic API Keys Doc](https://docs.atlas.mongodb.com/reference/api/apiKeys/).
## Configure connection
In addition to the parameters defined by the Secrets Engines Backend, this plugin has a number of parameters to further configure a connection.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/mongodbatlas/config` |
### Parameters
- `public_key` `(string: <required>)` – The Public Programmatic API Key used to authenticate with the MongoDB Atlas API.
- `private_key` `(string: <required>)` - The Private Programmatic API Key used to connect with MongoDB Atlas API.
### Sample payload
```json
{
"public_key": "yhltsvan",
"private_key": "2c130c23-e6b6-4da8-a93f-a8bf33218830"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/mongodbatlas/config
```
## Create/Update programmatic API key role
Programmatic API Key credential types create a Vault role to generate a Programmatic API Key at
either the MongoDB Atlas Organization or Project level with the designated role(s) for programmatic access. If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes.
| Method | Path |
| :----- | :------------- |
| `POST` | `/roles/:name` |
### Parameters
- `name` `(string <required>)` - Unique identifier name of the role name
- `organization_id` `(string <required>)` - Unique identifier for the organization to which
the target API Key belongs. Use the [orgs endpoint](https://www.mongodb.com/docs/atlas/reference/api/organization-get-all/)
to retrieve all organizations to which the authenticated user has access. Required if
`project_id` is not set.
- `project_id` `(string <required>)` - Unique identifier for the project to which the target
API Key belongs. Use the [projects endpoint](https://www.mongodb.com/docs/atlas/reference/api/project-get-all/)
to retrieve all organizations to which the authenticated user has access. Required if
`organization_id` is not set.
- `roles` `(list [string] <required>)` - List of roles that the API Key needs to have. If the roles array is provided:
-> **IMPORTANT:** Provide at least one role. Make sure all roles must be valid for the Organization or Project.
-> **NOTE:** Include all roles that you want this API Key to have. Any roles not in this array are removed.
- The Organization roles are:
- `ORG_OWNER`
- `ORG_MEMBER`
- `ORG_GROUP_CREATOR`
- `ORG_BILLING_ADMIN`
- `ORG_READ_ONLY`
- The Project roles are:
- `GROUP_CHARTS_ADMIN`
- `GROUP_CLUSTER_MANAGER`
- `GROUP_DATA_ACCESS_ADMIN`
- `GROUP_DATA_ACCESS_READ_ONLY`
- `GROUP_DATA_ACCESS_READ_WRITE`
- `GROUP_OWNER`
- `GROUP_READ_ONLY`
* `ip_addresses` `(list [string] <Optional>)` - IP address to be added to the whitelist for the API key. This field is mutually exclusive with the cidrBlock field.
* `cidr_blocks` `(list [string] <Optional>)` - Whitelist entry in CIDR notation to be added for the API key. This field is mutually exclusive with the ipAddress field.
* `project_roles` `(list [string] <Optional>)` - Roles assigned when an Organization API key is assigned to a Projects API key.
* `ttl` `(string <Optional>)` - Duration in seconds after which the issued credential should expire. Defaults to 0, in which case the value will fallback to the system/mount defaults.
* `max_ttl` `(string <Optional>)` - The maximum allowed lifetime of credentials issued using this role.
### Sample payload
```json
{
"project_id": "5cf5a45a9ccf6400e60981b6",
"roles": ["GROUP_CLUSTER_MANAGER"],
"cidr_blocks": ["192.168.1.3/32"],
"ip_addresses": ["192.168.1.3", "192.168.1.4"]
}
```
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key
```
### Sample response
```json
{
"project_id": "5cf5a45a9ccf6400e60981b6",
"roles": ["GROUP_CLUSTER_MANAGER"],
"cidr_blocks": ["192.168.1.3/32"],
"ip_addresses": ["192.168.1.3", "192.168.1.4"],
"organization_id": "7cf5a45a9ccf6400e60981b7",
"ttl": "30m",
"max_ttl": "1h"
}
```
## Read programmatic API key role
| Method | Path |
| :----- | :------------- |
| `GET` | `/roles/:name` |
### Parameters
- `name` `(string <required>)` - Unique identifier name of the role name
### Sample payload
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key
```
### Sample response
```json
{
"project_id": "5cf5a45a9ccf6400e60981b6",
"roles": ["GROUP_CLUSTER_MANAGER"],
"cidr_blocks": ["192.168.1.3/32"],
"ip_addresses": ["192.168.1.3", "192.168.1.4"],
"organization_id": "7cf5a45a9ccf6400e60981b7",
"ttl": "30m",
"max_ttl": "1h"
}
```
## List programmatic API key role
| Method | Path |
| :----- | :------- |
| `GET` | `/roles` |
### Sample payload
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/mongodbatlas/roles
```
### Sample response
```json
[
{
"project_id": "5cf5a45a9ccf6400e60981b6",
"roles": ["GROUP_CLUSTER_MANAGER"],
"cidr_blocks": ["192.168.1.3/32"],
"ip_addresses": ["192.168.1.3", "192.168.1.4"],
"organization_id": "7cf5a45a9ccf6400e60981b7",
"ttl": "30m",
"max_ttl": "1h"
},
{
"project_id": "5cf5a45a9ccf6400e60981b6",
"roles": ["READ"],
"cidr_blocks": ["192.168.1.3/35"],
"ip_addresses": ["192.168.1.5", "192.168.1.6"],
"organization_id": "7cf5a45a9ccf6400e60981b7",
"ttl": "30m",
"max_ttl": "1h"
}
]
```
## Delete programmatic API key role
| Method | Path |
| :------- | :------------- |
| `DELETE` | `/roles/:name` |
### Parameters
- `name` `(string <required>)` - Unique identifier name of the role name
### Sample payload
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
--data @payload.json \
http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key
```
## Read credential
| Method | Path |
| :----- | :------------- |
| `GET` | `/creds/:name` |
### Parameters
- `name` `(string <required>)` - Unique identifier name of the credential
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/mongodbatlas/creds/0fLBv1c2YDzPlJB1PwsRRKHR
```
### Sample response
```json
{
"lease_duration": "20s",
"lease_renewable": true,
"description": "vault-test-1563980947-1318",
"private_key": "905ae89e-6ee8-40rd-ab12-613t8e3fe836",
"public_key": "klpruxce"
}
```

335
website/content/api-docs/secret/nomad.mdx
View file

@ -1,335 +0,0 @@
---
layout: api
page_title: Nomad Secrets Engine- HTTP API
description: This is the API documentation for the Vault Nomad secrets engine.
---
> [!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.
# Nomad secrets engine (API)
@include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault Nomad secrets engine. For general
information about the usage and operation of the Nomad secrets engine, please see the
[Vault Nomad secrets engine documentation](/vault/docs/secrets/nomad).
This documentation assumes the Nomad secrets engine is mounted at the `/nomad` path
in Vault. Since it is possible to mount secrets engines 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 |
| :----- | :--------------------- |
| `POST` | `/nomad/config/access` |
### Parameters
- `address` `(string: "")` – Specifies the address of the Nomad
instance, provided as `"protocol://host:port"` like `"http://127.0.0.1:4646"`.
This value can also be provided on individual calls with the NOMAD_ADDR
environment variable.
- `token` `(string: "")` – Specifies the Nomad Management token to use.
This value can also be provided on individual calls with the NOMAD_TOKEN
environment variable.
- `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`.
- `ca_cert` `(string: "")` - CA certificate to use when verifying Nomad server certificate,
must be x509 PEM encoded.
- `client_cert` `(string: "")` - Client certificate used for Nomad's TLS communication,
must be x509 PEM encoded and if this is set you need to also set client_key.
- `client_key` `(string: "")` - Client key used for Nomad's TLS communication,
must be x509 PEM encoded and if this is set you need to also set client_cert.
### Sample payload
```json
{
"address": "http://127.0.0.1:4646",
"token": "adha...",
"max_token_name_length": 256
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/nomad/config/access
```
## Read access configuration
This endpoint queries for information about the Nomad connection.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `/nomad/config/access` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/nomad/config/access
```
### Sample response
```json
"data": {
"address": "http://localhost:4646/"
}
```
## Configure lease
This endpoint configures the lease settings for generated tokens.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/nomad/config/lease` |
### Parameters
- `ttl` `(string: "")` – Specifies the ttl for the lease. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_ttl` `(string: "")` – Specifies the max ttl for the lease. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"ttl": 1800,
"max_ttl": 3600
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/nomad/config/lease
```
## Read lease configuration
This endpoint queries for information about the Lease TTL for the specified mount.
| Method | Path |
| :----- | :-------------------- |
| `GET` | `/nomad/config/lease` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/nomad/config/lease
```
### Sample response
```json
"data": {
"max_ttl": 86400,
"ttl": 86400
}
```
## Delete lease configuration
This endpoint deletes the lease configuration.
| Method | Path |
| :------- | :-------------------- |
| `DELETE` | `/nomad/config/lease` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/nomad/config/lease
```
## 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 |
| :----- | :------------------ |
| `POST` | `/nomad/role/:name` |
### 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.
- `policies` `(string: "")` – Comma separated list of Nomad policies the token is going to be created against. These need to be created beforehand in Nomad.
- `global` `(bool: "false")` – Specifies if the token should be global, as defined in the [Nomad Documentation](/nomad/tutorials/access-control#acl-tokens).
- `type` `(string: "client")` - Specifies the type of token to create when
using this role. Valid values are `"client"` or `"management"`.
### Sample payload
To create a client token with a custom policy:
```json
{
"policies": "readonly"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/nomad/role/monitoring
```
## 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 |
| :----- | :------------------ |
| `GET` | `/nomad/role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to query. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/nomad/role/monitoring
```
### Sample response
```json
{
"data": {
"lease": "0s",
"policies": ["example"],
"token_type": "client"
}
}
```
## List roles
This endpoint lists all existing roles in the secrets engine.
| Method | Path |
| :----- | :---------------------- |
| `LIST` | `/nomad/role` |
| `GET` | `/nomad/role?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/nomad/role
```
### Sample response
```json
{
"data": {
"keys": ["example"]
}
}
```
## 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 |
| :------- | :------------------ |
| `DELETE` | `/nomad/role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--request DELETE \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/nomad/role/example-role
```
## Generate credential
This endpoint generates a dynamic Nomad token based on the given role
definition.
| Method | Path |
| :----- | :------------------- |
| `GET` | `/nomad/creds/:name` |
### 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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/nomad/creds/example
```
### Sample response
```json
{
"data": {
"accessor_id": "c834ba40-8d84-b0c1-c084-3a31d3383c03",
"secret_id": "65af6f07-7f57-bb24-cdae-a27f86a894ce"
}
}
```

4825
website/content/api-docs/secret/pki/index.mdx
View file

File diff suppressed because it is too large Load diff

1021
website/content/api-docs/secret/pki/issuance.mdx
View file

File diff suppressed because it is too large Load diff

313
website/content/api-docs/secret/rabbitmq.mdx
View file

@ -1,313 +0,0 @@
---
layout: api
page_title: RabbitMQ - Secrets Engines - HTTP API
description: This is the API documentation for the Vault RabbitMQ secrets engine.
---
> [!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.
# RabbitMQ secrets engine (API)
This is the API documentation for the Vault RabbitMQ secrets engine. For general
information about the usage and operation of the RabbitMQ secrets engine, please
see the [RabbitMQ documentation](/vault/docs/secrets/rabbitmq).
This documentation assumes the RabbitMQ secrets engine is enabled at the
`/rabbitmq` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
## Configure connection
This endpoint configures the connection string used to communicate with
RabbitMQ.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/rabbitmq/config/connection` |
### Parameters
- `connection_uri` `(string: <required>)` – Specifies the RabbitMQ connection URI.
- `username` `(string: <required>)` – Specifies the RabbitMQ management administrator username.
- `password` `(string: <required>)` – Specifies the RabbitMQ management administrator password.
- `verify_connection` `(bool: true)` – Specifies whether to verify connection URI, username, and password.
- `password_policy` `(string: "")` - Specifies a [password policy](/vault/docs/concepts/password-policies) to
use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set.
- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how
dynamic usernames are generated.
### Sample payload
```json
{
"connection_uri": "https://...",
"username": "user",
"password": "password",
"password_policy": "rabbitmq_policy"
}
```
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/rabbitmq/config/connection
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault write rabbitmq/config/connection \
connection_uri="http://localhost:8080" \
username="user" \
password="password" \
password_policy="rabbitmq_policy"
```
</Tab>
</Tabs>
## Configure lease
This endpoint configures the lease settings for generated credentials.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/rabbitmq/config/lease` |
### Parameters
- `ttl` `(int: 0)` – Specifies the lease ttl provided in seconds.
- `max_ttl` `(int: 0)` – Specifies the maximum ttl provided in seconds.
### Sample payload
```json
{
"ttl": 1800,
"max_ttl": 3600
}
```
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/rabbitmq/config/lease
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault write rabbitmq/config/lease \
ttl=1800 \
max_ttl=3600
```
</Tab>
</Tabs>
## Create role
This endpoint creates or updates the role definition.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/rabbitmq/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `tags` `(string: "")` – Specifies a comma-separated RabbitMQ management tags.
- `vhosts` `(string: "")` – Specifies a map of virtual hosts to
permissions.
- `vhost_topics` `(string: "")` – Specifies a map of virtual hosts and exchanges
to topic permissions. This option requires RabbitMQ 3.7.0 or later.
### Sample payload
```json
{
"tags": "tag1,tag2",
"vhosts": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}",
"vhost_topics": "{\"/\": {\"amq.topic\": {\"write\":\".*\", \"read\": \".*\"}}}"
}
```
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault write rabbitmq/roles/my-role \
tags="tag1,tag2" \
vhosts="..." \
vhost_topics="..."
```
</Tab>
</Tabs>
## Read role
This endpoint queries the role definition.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/rabbitmq/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is specified as part of the URL.
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault read rabbitmq/roles/my-role
```
</Tab>
</Tabs>
### Sample response
```json
{
"data": {
"tags": "",
"vhosts": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}",
"vhost_topics": "{\"/\": {\"amq.topic\": {\"write\":\".*\", \"read\": \".*\"}}}"
}
}
```
## Delete role
This endpoint deletes the role definition.
| Method | Path |
| :------- | :---------------------- |
| `DELETE` | `/rabbitmq/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is specified as part of the URL.
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```
</Tab>
<Tab heading="CLI">
```shell-session
vault delete rabbitmq/roles/my-role
```
</Tab>
</Tabs>
## Generate credentials
This endpoint generates a new set of dynamic credentials based on the named
role.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/rabbitmq/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is specified as part of the URL.
### Sample request
<Tabs>
<Tab heading="cURL">
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/rabbitmq/creds/my-role
```
</Tab>
<Tab heading="CLI">
```shell-session
$ vault read rabbitmq/creds/my-role
```
</Tab>
</Tabs>
### Sample response
```json
{
"data": {
"username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092",
"password": "e1b6c159-ca63-4c6a-3886-6639eae06c30"
}
}
```

960
website/content/api-docs/secret/ssh.mdx
View file

@ -1,960 +0,0 @@
---
layout: api
page_title: SSH - Secrets Engines - HTTP API
description: This is the API documentation for the Vault SSH secrets engine.
---
> [!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.
# SSH secrets engine (API)
This is the API documentation for the Vault SSH secrets engine. For general
information about the usage and operation of the SSH secrets engine, please see
the [SSH documentation](/vault/docs/secrets/ssh).
This documentation assumes the SSH secrets engine is enabled at the `/ssh` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.
## Create/Update role
This endpoint creates or updates a named role.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/ssh/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is part of the request URL.
- `default_user` `(string: "")` – Specifies the default username for which a
credential will be generated. When the endpoint `creds/` is used without a
username, this value will be used as default username. Its recommended to
create individual roles for each username to ensure absolute isolation between
usernames. This is required for OTP type roles.
When `default_user_template` is set to `true`, this field can contain an identity
template with any prefix or suffix, like `ssh-{{identity.entity.id}}-user`.
For the CA type, if you wish this to be a valid principal, it must also be
in `allowed_users`.
- `default_user_template` `(bool: false)` - If set, `default_users` can be specified
using identity template values. A non-templated user is also permitted.
- `cidr_list` `(string: "")` – Specifies a comma separated list of CIDR blocks
for which the role is applicable for. It is possible that a same set of CIDR
blocks are part of multiple roles. This is a required parameter, unless the
role is registered under the `/config/zeroaddress` endpoint. Note:
[Not applicable for CA type]
- `exclude_cidr_list` `(string: "")` – Specifies a comma-separated list of CIDR
blocks. IP addresses belonging to these blocks are not accepted by the role.
This is particularly useful when big CIDR blocks are being used by the role
and certain parts need to be kept out. Note:
[Not applicable for CA type]
- `port` `(int: 22)` – Specifies the port number for SSH connection. Port number
does not play any role in OTP generation. For the `otp` secrets engine type, this is
just a way to inform the client about the port number to use. The port number
will be returned to the client by Vault along with the OTP.
- `key_type` `(string: <required>)` – Specifies the type of credentials
generated by this role. This can be either `otp` or `ca`.
- `allowed_users` `(string: "")` – If this option is not specified, or if it is
`*`, the client can request a credential for any valid user at the remote
host, including the admin user. To only allow an explicit list of users, set
this parameter using a comma-separated username list to enforce it. When this
parameter is set, the credentials are created only for `default_user` and
usernames listed. Setting this option will enable all the users with access
this role to fetch credentials for all other usernames in this list.
When `allowed_users_template` is set to `true`, this field can contain an identity
template with any prefix or suffix, like `ssh-{{identity.entity.id}}-user`.
Use with caution. N.B.: if the type is `ca`, an empty list does not allow any user;
instead you must use `*` to enable this behavior.
- `allowed_users_template` `(bool: false)` - If set, `allowed_users` can be specified
using identity template policies. Non-templated users are also permitted.
- `allowed_domains` `(string: "")` – A comma-separated list of domains for which
a client can request a host certificate. If this option is explicitly set to
`"*"`, then credentials can be created for any domain. See also
`allow_bare_domains` and `allow_subdomains`.
- `allowed_domains_template` `(bool: false)` - If set, `allowed_domains` can be
specified using identity template policies. Non-templated domains are also
permitted.
- `ttl` `(string: "")` – Specifies the Time To Live value provided as a string
duration with time suffix. Hour is the largest suffix. If not set, uses the
system default value or the value of `max_ttl`, whichever is shorter.
- `max_ttl` `(string: "")` – Specifies the maximum Time To Live provided as a
string duration with time suffix. Hour is the largest suffix. If not set,
defaults to the system maximum lease TTL.
- `allowed_critical_options` `(string: "")` – Specifies a comma-separated list
of critical options that certificates can have when signed. To allow any
critical options, set this to an empty string. Will default to allowing any
critical options.
- `allowed_extensions` `(string: "")` – Specifies a comma-separated list of
extensions that certificates can have when signed. To allow a user to specify
any extension, set this to `"*"`. If not set, users will not be allowed to
specify extensions and will get the extensions specified within `default_extensions`.
For the list of extensions, take a look at the [sshd
manual's](https://man.openbsd.org/sshd#AUTHORIZED_KEYS_FILE_FORMAT)
`AUTHORIZED_KEYS FILE FORMAT` section. You should add a `permit-` before the
name of extension to allow it.
- `default_critical_options` `(map<string|string>: "")` – Specifies a map of
critical options certificates should have if none are provided when signing.
This field takes in key value pairs in JSON format. Note that these are not
restricted by `allowed_critical_options`. Defaults to none.
- `default_extensions` `(map<string|string>: "")` – Specifies a map of
extensions certificates should have if none are provided when signing. This
field takes in key value pairs in JSON format. Note that these are not
restricted by `allowed_extensions`. Defaults to none.
- `default_extensions_template` `(bool: false)` - If set, `default_extensions` can be specified
using identity template values. A non-templated user is also permitted.
- `allow_user_certificates` `(bool: false)` – Specifies if certificates are
allowed to be signed for use as a 'user'.
- `allow_host_certificates` `(bool: false)` – Specifies if certificates are
allowed to be signed for use as a 'host'.
- `allow_bare_domains` `(bool: false)` – Specifies if host certificates that are
requested are allowed to use the base domains listed in `allowed_domains`, e.g.
"example.com". This is a separate option as in some cases this can be
considered a security threat.
- `allow_subdomains` `(bool: false)` – Specifies if host certificates that are
requested are allowed to be subdomains of those listed in `allowed_domains`,
e.g. if "example.com" is part of `allowed_domains`, this allows
"foo.example.com".
- `allow_user_key_ids` `(bool: false)` – Specifies if users can override the key
ID for a signed certificate with the "key_id" field. When false, the key ID
will always be the token display name. The key ID is logged by the SSH server
and can be useful for auditing.
- `key_id_format` `(string: "")` – When supplied, this value specifies a custom
format for the key id of a signed certificate. The following variables are
available for use: '{{token_display_name}}' - The display name of the token used
to make the request. '{{role_name}}' - The name of the role signing the request.
'{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed.
e.g. "custom-keyid-{{token_display_name}}"
- `allowed_user_key_lengths` `(map<string|(int|[]int|string)>: "")` – Specifies a
map of ssh key types and their expected sizes which are allowed to be signed by
the CA type. To specify multiple sizes, either use a comma-separated list or an
array of allowed key widths. We support both OpenSSH-style key identifiers and
short names (`rsa`, `ecdsa`, `dsa`, or `ed25519`) as keys. For example, a valid
policy to allow common RSA and ECDSA key lengths might be:
```
{
"rsa": [2048, 3072, 4096],
"ec": 256,
"ecdsa-sha2-nistp521": 0
}
```
Note that when an algorithm identifier uniquely specifies a key length (such as
with `ecdsa-sha2-nistp256` or `ed25519`), the value of the length is ignored (and
can be zero).
- `allow_empty_principals` `(bool: false)` - Allow signing certificates with
no valid principals (e.g. any valid principal). For backwards
compatibility only. The default of false is highly recommended.
- `algorithm_signer` `(string: "default")` - Algorithm to sign keys with. Valid
values are `ssh-rsa`, `rsa-sha2-256`, `rsa-sha2-512`, or `default`. This
value may also be left blank to use the signer's default algorithm, and must
be left blank or have value `default` for CA key types other than RSA.
~> **Note**: The value of `default` may change over time as vulnerabilities
in algorithms are discovered. The present value for RSA keys is equivalent
to `rsa-sha2-256`.
~> **Warning**: The `algorithm_signer` value `ssh-rsa` uses the SHA-1 hash
algorithm. This algorithm is now considered insecure and is not supported by
current OpenSSH versions. As a result, Vault has made the new default
`rsa-sha2-256` for RSA CA keys. It is strongly encouraged for all users to
migrate to `rsa-sha2-256` or `default` if the role was created with an
explicit `algorithm_signer=rsa-sha` parameter or has been migrated to such.
- `not_before_duration` `(duration: "30s")` – Specifies the duration by which to
backdate the `ValidAfter` property. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"key_type": "otp"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/roles/my-role
```
## Read role
This endpoint queries a named role.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/ssh/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/ssh/roles/my-role
```
### Sample response
For an OTP role:
```json
{
"cidr_list": "x.x.x.x/y",
"default_user": "username",
"key_type": "otp",
"port": 22
}
```
For a CA role:
```json
{
"allow_bare_domains": false,
"allow_host_certificates": true,
"allow_subdomains": false,
"allow_user_key_ids": false,
"allow_user_certificates": true,
"allowed_critical_options": "",
"allowed_extensions": "",
"default_critical_options": {},
"default_extensions": {},
"max_ttl": "768h",
"ttl": "4h"
}
```
## List roles
This endpoint returns a list of available roles. Only the role names are
returned, not any values.
| Method | Path |
| :----- | :----------- |
| `LIST` | `/ssh/roles` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/ssh/roles
```
### Sample response
```json
{
"auth": null,
"data": {
"keys": ["dev", "prod"],
"key_info": {
"dev": {
"key_type": "ca"
}
}
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Delete role
This endpoint deletes a named role.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `/ssh/roles/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/roles/my-role
```
## List Zero-Address roles
This endpoint returns the list of configured zero-address roles.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/ssh/config/zeroaddress` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"roles": ["otp_key_role"]
},
"warnings": null,
"auth": null
}
```
## Configure Zero-Address roles
This endpoint configures zero-address roles.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/ssh/config/zeroaddress` |
### Parameters
- `roles` `(string: <required>)` – Specifies a string containing comma separated
list of role names which allows credentials to be requested for any IP
address. CIDR blocks previously registered under these roles will be ignored.
### Sample payload
```json
{
"roles": ["otp_key_role"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```
## Delete Zero-Address role
This endpoint deletes the zero-address roles configuration.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `/ssh/config/zeroaddress` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```
## Generate SSH credentials
This endpoint creates credentials for a specific username and IP with the
parameters defined in the given role.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/ssh/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is part of the request URL.
- `username` `(string: "")` – Specifies the username on the remote host.
- `ip` `(string: <required>)` – Specifies the IP of the remote host.
### Sample payload
```json
{
"ip": "1.2.3.4"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/creds/my-role
```
### Sample response
For an OTP role:
```json
{
"lease_id": "sshs/creds/c3c2e60c-5a48-415a-9d5a-a41e0e6cdec5/3ee6ad28-383f-d482-2427-70498eba4d96",
"renewable": false,
"lease_duration": 2764800,
"data": {
"ip": "127.0.0.1",
"key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2",
"key_type": "otp",
"port": 22,
"username": "rajanadar"
},
"warnings": null,
"auth": null
}
```
## List roles by IP
This endpoint lists all of the roles with which the given IP is associated.
| Method | Path |
| :----- | :------------ |
| `POST` | `/ssh/lookup` |
### Parameters
- `ip` `(string: <required>)` – Specifies the IP of the remote host.
### Sample payload
```json
{
"ip": "1.2.3.4"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/lookup
```
### Sample response
An array of roles as a secret structure.
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"roles": [
"fe6f61b7-7e4a-46a6-b2c8-0d530b8513df",
"6d6411fd-f622-ea0a-7e2c-989a745cbbb2"
]
},
"warnings": null,
"auth": null
}
```
## Verify SSH OTP
This endpoint verifies if the given OTP is valid. This is an unauthenticated
endpoint.
| Method | Path |
| :----- | :------------ |
| `POST` | `/ssh/verify` |
### Parameters
- `otp` `(string: <required>)` – Specifies the One-Time-Key that needs to be
validated.
### Sample payload
```json
{
"otp": "bad2b3-..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/verify
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"ip": "127.0.0.1",
"username": "rajanadar"
},
"warnings": null,
"auth": null
}
```
## Submit CA information
This endpoint allows submitting the CA information for the secrets engine via an SSH
key pair. _If you have already set a certificate and key, they will be
overridden._
| Method | Path |
| :----- | :--------------- | -------------------------- |
| `POST` | `/ssh/config/ca` | `200/204 application/json` |
### Parameters
- `private_key` `(string: "")` – Specifies the private key part the SSH CA key
pair; required if `generate_signing_key` is false.
- `public_key` `(string: "")` – Specifies the public key part of the SSH CA key
pair; required if `generate_signing_key` is false.
- `generate_signing_key` `(bool: true)` – Specifies if Vault should generate
the signing key pair internally. If `true`, an RSA key pair is generated, and
the generated public key is returned so you can add it to your configuration.
If `false`, then you must provide `private_key` and `public_key`, but these
can be of any valid signing key type.
- `key_type` `(string: ssh-rsa)` - Specifies the desired key type for the
generated SSH CA key when `generate_signing_key` is set to `true`. Valid
values are OpenSSH key type identifiers (`ssh-rsa`, `ecdsa-sha2-nistp256`,
`ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, or `ssh-ed25519`) or an
algorithm (`rsa`, `ec`, or `ed25519`).
- `key_bits` `(int: 0)` - Specifies the desired key bits for the generated SSH
CA key when `generate_signing_key` is set to `true`. This is only used for
variable length keys (such as `ssh-rsa`, where the value of `key_bits`
specifies the size of the RSA key pair to generate; with the default `0`
value resulting in a 4096-bit key) or when the `ec` algorithm is specified
in `key_type` (where the value of `key_bits` identifies which NIST P-curve
to use; `256`, `384`, or `521`, with the default `0` value resulting in a
NIST P-256 key).
- `managed_key_name` `(string:"")` <EnterpriseAlert inline="true" /> -
The name of the managed key to use. When using a managed key, this field or
managed_key_id is required.
- `managed_key_id` `(string:"")` <EnterpriseAlert inline="true" /> -
The id of the managed key to use. When using a managed key, this field or
managed_key_name is required.
### Sample payload
```json
{
"generate_signing_key": true
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/config/ca
```
### Sample response
This will return a `204` response if `generate_signing_key` was unset or false.
This will return a `200` response if `generate_signing_key` was true:
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"public_key": "ssh-rsa AAAAHHNzaC1y...\n"
},
"warnings": null
}
```
## Delete CA information
This endpoint deletes the CA information for the backend via an SSH key pair.
| Method | Path |
| :------- | :--------------- |
| `DELETE` | `/ssh/config/ca` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/ssh/config/ca
```
## Read public key (Unauthenticated)
This endpoint returns the configured/generated public key. This is an unauthenticated
endpoint.
~> Note: this is a raw response endpoint without JSON encoding; use
`vault read -format=raw` or an external tool (e.g., `curl`) to fetch this
value.
| Method | Path | Content-Type |
| :----- | :---------------- | ---------------- |
| `GET` | `/ssh/public_key` | `200 text/plain` |
### Sample request
```shell-session
$ curl http://127.0.0.1:8200/v1/ssh/public_key
```
### Sample response
```text
ssh-rsa AAAAHHNzaC1y...
```
## Read public key (Authenticated)
This endpoint reads the configured/generated public key.
| Method | Path |
| :----- | :--------------- |
| `GET` | `/ssh/config/ca` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/ssh/config/ca
```
### Sample response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"public_key": "ssh-rsa AAAAHHNzaC1y...\n"
},
"warnings": null
}
```
## Sign SSH key
This endpoint signs an SSH public key based on the supplied parameters and
subject to the restrictions of the role named in the path. Both `create` and
`update` policy capabilities are needed to sign and update SSH keys. If only
`create` capability is granted, and a SSH key does not exist, it will be created
using the default parameters already configured. If only `update` capability is
available and a SSH key does not exist, an error will be returned and SSH keys
must exist already before may be updated.
It is similar to the endpoint `/ssh/issue/:name`. Instead of issuing new
SSH credentials, this returns a certificate for the given SSH public key.
The issued certificate uses the defaults specified in the role named in
this endpoint. Where not restricted by the parameters of this role, the
parameters of the issued certificate can be further customized in this API call.
~> **Note**: The issued certificate is returned but _not_ stored by Vault.
If you do not save it from the response, request it again by repeating
this request.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/ssh/sign/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to sign. This
is part of the request URL.
- `public_key` `(string: <required>)` – Specifies the SSH public key that should
be signed.
- `ttl` `(string: "")` – Specifies the Requested Time To Live. Cannot be greater
than the role's `max_ttl` value. If not provided, the role's `ttl` value will
be used. Note that the role values default to system values if not explicitly
set.
- `valid_principals` `(string: "")` – Specifies valid principals, either
usernames or hostnames, that the certificate should be signed for. Required
unless the role has specified allow_empty_principals or a value has been set for
either the default_user or default_user_template role parameters.
- `cert_type` `(string: "user")` – Specifies the type of certificate to be
created; either "user" or "host".
- `key_id` `(string: "")` – Specifies the key id that the created certificate
should have. If not specified, the display name of the token will be used.
- `critical_options` `(map<string|string>: "")` – Specifies a map of the
critical options that the certificate should be signed for. Defaults to none.
- `extensions` `(map<string|string>: "")` – Specifies a map of the extensions
that the certificate should be signed for. Defaults to none.
### Sample payload
```json
{
"public_key": "ssh-rsa ..."
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/sign/my-key
```
### Sample response
```json
{
"lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993",
"renewable": false,
"lease_duration": 21600,
"data": {
"serial_number": "f65ed2fd21443d5c",
"signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n"
},
"auth": null
}
```
## Generate certificate and key
This endpoint issues a new set of SSH credentials (private key and certificate).
It is similar to the endpoint `/ssh/sign/:name`: Instead of signing an existing
SSH public key, it generates and issues new SSH credentials (key and certificate).
The issued certificate uses the defaults specified in the role named in
this endpoint. Where not restricted by the parameters of this role, the
parameters of the issued certificate can be further customized in this API call.
~> **Note**: The issued credentials are returned but _not_ stored by Vault.
If you do not save them from the response, issue new credentials by using
this request again. This endpoint is available with Vault version 1.12+.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/ssh/issue/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create the
certificate against. This is part of the request URL.
- `key_type` `(string: "rsa")` – Specifies the desired key type; must be `rsa`, `ed25519`
or `ec`.
- `key_bits` `(int: 0)` – Specifies the number of bits to use for the
generated keys. Allowed values are 0 (universal default); with
`key_type=rsa`, allowed values are: 2048 (default), 3072, or
4096; with `key_type=ec`, allowed values are: 256 (default), 384,
or 521; ignored with `key_type=ed25519`.
- `ttl` `(string: "")` – Specifies the Requested Time To Live. Cannot be greater
than the role's `max_ttl` value. If not provided, the role's `ttl` value will
be used. Note that the role values default to system values if not explicitly
set.
- `valid_principals` `(string: "")` – Specifies valid principals, either
usernames or hostnames, that the certificate should be signed for. Required
unless the role has specified allow_empty_principals.
- `cert_type` `(string: "user")` – Specifies the type of certificate to be
created; either "user" or "host".
- `key_id` `(string: "")` – Specifies the key id that the created certificate
should have. If not specified, the display name of the token will be used.
- `critical_options` `(map<string|string>: "")` – Specifies a map of the
critical options that the certificate should be signed for. Defaults to none.
- `extensions` `(map<string|string>: "")` – Specifies a map of the extensions
that the certificate should be signed for. Defaults to none.
### Sample payload
```json
{
"key_type": "rsa",
"key_bits": 2048
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ssh/issue/my-role
```
### Sample response
```json
{
"request_id": "94fd1102-08a1-c207-0e3e-657e8f80c09e",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"serial_number": "1e965817eb12a511",
"signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHN...\n",
"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAwer03vkQrPV+wWpbisJJv2CKqHmMz+Ej0ctLbhpOmR2CY9S9\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n",
"private_key_type": "rsa"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Tidy host keys
This endpoint removes all existing host keys from Vault, if any are present.
These keys were used with the Dynamic Keys functionality, which were removed
from this engine.
~> Note: This does not clean up any pending dynamic key leases and will not
remove these keys from systems with authorized hosts entries created by
Vault. That must be done manually by an operator, potentially before the
removal of these host keys if they are necessary to access these
systems.<br /><br />
For a more effective cleanup process, it is suggest to stay on Vault 1.12,
manually revoke all dynamic key leases, wait for this to finish, and then
upgrade to Vault 1.13+.
| Method | Path |
| :------- | :----------------------- |
| `DELETE` | `/ssh/tidy/dynamic-keys` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/ssh/issue/my-role
```
### Sample response
```json
{
"request_id": "",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"message": "Removed 15 of 15 host keys."
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Managed keys
~> Note: Managed keys are an Enterprise only feature.
The [Submit CA information](#submit-ca-information) API call can leverage the
Managed Keys feature, delegating operations that require private key material
to an external system.
To leverage a Managed Key, assuming it has already been configured, set either the
`managed_key_name` or `managed_key_id` parameter specifying a Managed Key to use.
If Managed Key parameters are provided, parameters for generating or providing
key material will be ignored, including the `generate_signing_key` parameter. Key
generation with Managed Keys must be configured in the creation of the Managed Key.
The API call will fail if the specified Managed Key is not properly configured.
Once the CA has been configured with a Managed Key, other SSH operations behave
the same, with no other special configuration or parameters required.

323
website/content/api-docs/secret/terraform.mdx
View file

@ -1,323 +0,0 @@
---
layout: api
page_title: Terraform Cloud Secret Backend - HTTP API
description: This is the API documentation for the Vault Terraform Cloud secret backend.
---
> [!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.
# Terraform Cloud secret backend HTTP API
This is the API documentation for the Vault Terraform Cloud secret backend. For general
information about the usage and operation of the Terraform Cloud backend, please see the
[Vault Terraform Cloud backend documentation](/vault/docs/secrets/terraform).
This documentation assumes the Terraform Cloud backend is mounted at the `/terraform` 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 Terraform Cloud. This access
information is used so that Vault can communicate with Terraform Cloud and generate
Terraform Cloud tokens.
| Method | Path |
| :----- | :------------------ |
| `POST` | `/terraform/config` |
### Parameters
- `address` `(string: "")` – Specifies the address of the Terraform Cloud
server, if using Terraform Enterprise, provided as `"protocol://host:port"`.
The default is `https://app.terraform.io` for Terraform Cloud.
- `token` `(string: "")` – Specifies the Terraform Cloud authentication token to
use. This token must have the needed permissions to manage all Organization,
Team, and User tokens desired for this mount.
### Sample payload
```json
{
"address": "https://app.terraform.io",
"token": "glhf..."
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/terraform/config
```
## Read access configuration
This endpoint queries for information about the Terraform Cloud connection.
| Method | Path |
| :----- | :------------------ |
| `GET` | `/terraform/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/terraform/config
```
### Sample response
```json
"data": {
"address": "https://app.terraform.io",
"base_path": "/api/v2/"
}
```
## Create/Update role
This endpoint creates or updates the Terraform Cloud role definition in Vault.
If the role does not exist, it will be created. If the role already exists, it
will receive updated attributes.
Terraform Cloud offers four distinct types of API tokens with varying level of
access: Organizations, Teams, Legacy Teams (deprecated in HCP Terraform) and Users.
A Vault Role can manage a single type of API token at a time, determined by how it is configured:
- To manage an Organization API token, provide the organization
name with the `organization` parameter
- To manage a Team API token, provide the `team_id` parameter and set the
`credential_type` parameter to `team`
- To manage a Legacy Team API token, provide the `team_id` parameter and set the
`credential_type` parameter to `team_legacy`
- To manage a User API token, provide a `user_id` parameter
~> **Special Note:** Organizations and Legacy Teams can only have a single active API
token at any given time. Generating a new token for an organization or legacy team will
effectively revoke any existing tokens, regardless if those tokens were
originally created by Vault. As such, requesting an Organization or Legacy Team token
from Vault will return the same token indefinitely until that token is rotated
with the `/rotate-role` endpoint.
Please see the [Terraform Cloud API
Token documentation for more
information](/terraform/cloud-docs/users-teams-organizations/api-tokens).
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/terraform/role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name for the Vault role. This is
part of the request URL.
- `organization` `(string: "")` – Organization name to manage the single API
token. Organizations can only have a single active API token at any given
time. Conflicts with `user_id`.
- `team_id` `(string: "")` – Team ID to manage the single API token. Teams can
only have a single active API token at any given time. Conflicts with
`user_id`.
- `user_id` `(string: "")` – User ID to manage dynamic tokens. Conflicts with
`organization` and `team_id`.
- `credential_type` `(string: "")` – Specifies the type of credential to generate.
If unspecified, Vault sets it automatically based on the type of id (defaults to
`team_legacy` if setting `team_id`). Valid values are `team`, `team_legacy`,
`user`, or `organization`.
- `description` `(string: "")` - Description of the role. Applies to User and
Team API tokens. Used as a prefix to help identify the token in the HCP Terraform UI.
- `ttl` `(duration: "")` – Specifies the TTL for this role. If not
provided, the default Vault TTL is used. Applies to User and Team API tokens.
Uses [duration format strings](/vault/docs/concepts/duration-format).
- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
provided, the default Vault Max TTL is used. Applies to User and Team API tokens.
Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
To create a Vault role to manage Terraform Cloud User tokens
```json
{
"user_id": "user-glhf1234",
"credential_type": "user",
"description": "description",
"ttl": "1h",
"max_ttl": "24h"
}
```
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
--data @payload.json \
http://127.0.0.1:8200/v1/terraform/role/tfuser
```
## Read role
This endpoint queries for information about a Terraform Cloud role with the given name.
If no role exists with that name, a 404 is returned.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/terraform/role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to query. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/terraform/role/tfuser
```
### Sample response
```json
{
"data": {
"credential_type": "user",
"description": "description",
"max_ttl": 86400,
"name": "tfuser",
"ttl": 3600,
"user_id": "user-glhf1234"
}
}
```
## List roles
This endpoint lists all existing roles in the backend.
| Method | Path |
| :----- | :-------------------------- |
| `LIST` | `/terraform/role` |
| `GET` | `/terraform/role?list=true` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/terraform/role
```
### Sample response
```json
{
"data": {
"keys": ["tfuser"]
}
}
```
## Delete role
This endpoint deletes a Terraform Cloud role with the given name. Even if the role does
not exist, this endpoint will still return a successful response.
| Method | Path |
| :------- | :---------------------- |
| `DELETE` | `/terraform/role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--request DELETE \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/terraform/role/tfuser
```
## Rotate role
This endpoint rotates the credentials for a Terraform Cloud role that manages an
Organization or Legacy Team. This endpoint is only valid for those roles;
attempting to rotate a role that manages User or Team tokens will result in an error.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/terraform/rotate-role/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to rotate. This
is part of the request URL.
### Sample request
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/terraform/rotate-role/testing
```
## Generate credential
This endpoint returns a Terraform Cloud token based on the given role
definition. For Organization and Legacy Team roles, the same API token is returned
until the token is rotated with `rotate-role`. For User and Team roles, a new token is
generated with each request.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/terraform/creds/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of an existing role against
which to create this Terraform Cloud token. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/terraform/creds/example
```
### Sample response
```json
{
"request_id": "71629848-778d-f9ae-c396-0b02fae2adda",
"lease_id": "terraform/creds/tfuser/dWa2E5aiIX7jJfyMqPm1fSPr",
"lease_duration": 60,
"renewable": true,
"data": {
"token": "<example-token>",
"token_id": "at-example"
},
"warnings": null
}
```

272
website/content/api-docs/secret/totp.mdx
View file

@ -1,272 +0,0 @@
---
layout: api
page_title: TOTP - Secrets Engines - HTTP API
description: This is the API documentation for the Vault TOTP secrets engine.
---
> [!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.
# TOTP secrets engine (API)
This is the API documentation for the Vault TOTP secrets engine. For general
information about the usage and operation of the TOTP secrets engine, please see
the [TOTP documentation](/vault/docs/secrets/totp).
This documentation assumes the TOTP secrets engine is enabled at the `/totp`
path in Vault. Since it is possible to enable secrets engines at any location,
please update your API calls accordingly.
## Create key
This endpoint creates or updates a key definition.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/totp/keys/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to create. This is specified as part of the URL.
- `generate` `(bool: false)` – Specifies if a key should be generated by Vault or if a key is being passed from another service.
- `exported` `(bool: true)` – Specifies if a QR code and url are returned upon generating a key. Only used if generate is true.
- `key_size` `(int: 20)` – Specifies the size in bytes of the Vault generated key. Only used if generate is true.
- `url` `(string: "")` – Specifies the TOTP key url string that can be used to configure a key. Only used if generate is false.
- `key` `(string: <required - if generate is false and url is empty>)` – Specifies the root key used to generate a TOTP code. Only used if generate is false.
- `issuer` `(string: "" <required - if generate is true>)` – Specifies the name of the key’s issuing organization.
- `account_name` `(string: "" <required - if generate is true>)` – Specifies the name of the account associated with the key.
- `period` `(int or duration format string: 30)` – Specifies the length of time in seconds used to generate a counter for the TOTP code calculation.
- `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".
- `digits` `(int: 6)` – Specifies the number of digits in the generated TOTP code. This value can be set to 6 or 8.
- `skew` `(int: 1)` – Specifies the number of delay periods that are allowed when validating a TOTP code. This value can be either 0 or 1. Only used if generate is true.
- `qr_size` `(int: 200)` – Specifies the pixel size of the square QR code when generating a new key. Only used if generate is true and exported is true. If this value is 0, a QR code will not be returned.
### Sample payload
```json
{
"url": "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/totp/keys/my-key
```
### Sample payload
```json
{
"generate": true,
"issuer": "Google",
"account_name": "test@gmail.com"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/totp/keys/my-key
```
### Sample response
```json
{
"data": {
"barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGXklEQVR4nOyd4Y4iOQyEmRPv/8p7upX6BJm4XbbDbK30fT9GAtJJhpLjdhw3z1+/HmDEP396AvDO878/X1+9i1frWvu5Po/6Xz+P2kft1nFVa1f7z+YdjT/5PrEQMxDEDAQx4/n6orsGr6z9ZP1mviMbP/MBav/R6/U61Ud0vk8sxAwEMQNBzHju3lTvv6P2ajwS9Ve9zz+9pkfjRp+r/SjzwULMQBAzEMSMrQ/pUo0bouun7dW9LXVvrBq/TMBCzEAQMxDEjKM+JFqT17W4mu9Y+49eq/OL3r/GVX3CJ7KtWIgZCGIGgpix9SHTtXGa4476qfoa1adVc+HV/6/yfWIhZiCIGQhixpsP6Z4nulD3lqavV7q+Yvo6G7/zfWIhZiCIGQhixteJ/Rh1Da3e71d9RjRul2ocdeK7xELMQBAzEMSM3z6ku6dTrdOo1l9M6y5O7clVx5n4SCzEDAQxA0HMuN3L+qlavqj9itpePY+VtVdrHqfzeQULMQNBzEAQM97ikAv1vr/brltTeCp/svarcjLe2F1PnbohCGIGgphRqjG8mJ6PmtYMVnP363Vqv6d8qZrzf2AhfiCIGQhixm0c8n+jQ8+7+jZ4cY3PrlfHO/1Ml+45st18sRAzEMQMBDHjdxyixgPqs0lWsvvwqH00zrSO41R80p3XXXssxAwEMQNBzJCeuaieo6pedzGtb1/76fqgLH6ofg+dZ65gIWYgiBkIYsbbs9/V+/EVde1V+62eh1I/r/qIrs+Ixo2uYy/LGAQxA0HMeNvLilDX1OraXc2jVNtPzxJXr6v+HzuwEDMQxAwEMWNbp95d21WmzzBR6066e07dPMq0XoW9LEMQxAwEMUOqUz+1p9ONd07Xz586u6yifp/4EEMQxAwEMUPay7rIcthqTrx6v1/NTX+qZrIbF63v34GFmIEgZiCIGdvfU++e1a3GM2oOPjtvpfbfjS+qeZFJXgcLMQNBzEAQM6Tn9p7OLVdrFqP5TFF9ZXTdqfqTV7AQMxDEDAQx482HdPMPGdN8SjeHr6710zzJidrCB/kQTxDEDAQxY7uXdTGNC9S9pK6vqs6nWzdyej53PhELMQNBzEAQM0o59YtTz/xQfVO3jmOdl0rmE6f5ort5YSFmIIgZCGLGbU69eka3ep+v5sCzcbp5jZXMR0zr+aPPqVM3BkHMQBAzRs/tjejmwj9d05ihzq96nQr5EEMQxAwEMWPrQy6q9/fdevFTcVA0v+n5K7U/tf4lGhcfYgiCmIEgZtw+6+RCXUurvkKlepZ2vS5i+oyTaby0GxcLMQNBzEAQM0r5kKnv6K6xK9X4R13zu+eyJnXpazssxAwEMQNBzNj+fkg3nqjGK9laPz1vleXwq2v+p+vciUMMQRAzEMSM298xrOYDVqrtpmtzt59uHqc6v2zcBxbiB4KYgSBmbOvUV7q577VdOIliXqLr87p7Tere2YnrsRAzEMQMBDFj+zuGar3Gp+rNp3kUtR5lmj/Jxo/GvZsvFmIGgpiBIGbcPi/rW+MPPaeqOs407xL1E1E9lzWpg8FCzEAQMxDEDOk3qC66a7f6fsSn1uz18+o8P+GzsBAzEMQMBDFjm1Ov7L3s3p+2/6lcfoa6ZxaNm50DWyEOMQRBzEAQM7Zne6PX3XilW5M3zbd0c/3ZHpvqY6P+7j7HQsxAEDMQxIxRPqRaT6Kuzemkh7WJ3RrJbJxq7eOuPyzEDAQxA0HMKJ3t/XbxobW/Gmdka/PpPMxPgoWYgSBmIIgZ0m9QrXTP1mb9Ru2y+/hsD2xaM9jN5UfjEIf8RSCIGQhiRus3qLp7ONU6jK4vynxMdn10XdY+m4/SHxZiBoKYgSBm3MYhGdl9/qkzvN18ilpDqF6nxiPVGs3Xz7EQMxDEDAQx4/ZcVoR6fqobZ6h7Vtm81TVejZdWuvHNXXssxAwEMQNBzHju3pyujdO68Ky9Wm+h9qPGJVG/6nyU+WIhZiCIGQhixtaHdFF9hlqLeOrcVPcMQDeOmtTNYyFmIIgZCGLGUR/SPQs73QuL5tGtiVznlc1X/T8iXtthIWYgiBkIYsbWh3T3nNS1dXqe6tReW8S0Hr1b5/LAQvxAEDMQxIw3H9I9nzU9R6XGHdn41dx4d4+rGp9En7OX9ReAIGYgiBlff6IWG2KwEDP+DQAA//+TDHXGhqE4+AAAAABJRU5ErkJggg==",
"url": "otpauth://totp/Google:test@gmail.com?algorithm=SHA1&digits=6&issuer=Google&period=30&secret=HTXT7KJFVNAJUPYWQRWMNVQE5AF5YZI2"
}
}
```
If a QR code is returned, it consists of base64-formatted PNG bytes. You can embed it in a web page by including the base64 string in an `img` tag with the prefix `data:image/png;base64`
```
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUh.." />
```
## Read key
This endpoint queries the key definition.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/totp/keys/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to read. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/totp/keys/my-key
```
### Sample response
```json
{
"data": {
"account_name": "test@gmail.com",
"algorithm": "SHA1",
"digits": 6,
"issuer": "Google",
"period": 30
}
}
```
## List keys
This endpoint returns a list of available keys. Only the key names are
returned, not any values.
| Method | Path |
| :----- | :----------- |
| `LIST` | `/totp/keys` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/totp/keys
```
### Sample response
```json
{
"auth": null,
"data": {
"keys": ["my-key"]
},
"lease_duration": 0,
"lease_id": "",
"renewable": false
}
```
## Delete key
This endpoint deletes the key definition.
| Method | Path |
| :------- | :----------------- |
| `DELETE` | `/totp/keys/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to delete. This
is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/totp/keys/my-key
```
## Generate code
This endpoint generates a new time-based one-time use password based on the named
key.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/totp/code/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key to create
credentials against. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/totp/code/my-key
```
### Sample response
```json
{
"data": {
"code": "810920"
}
}
```
## Validate code
This endpoint validates a time-based one-time use password generated from the named
key.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/totp/code/:name` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the key used to generate the password. This is specified as part of the URL.
- `code` `(string: <required>)` – Specifies the password you want to validate.
### Sample payload
```json
{
"code": "123802"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/totp/code/my-key
```
### Sample response
```json
{
"data": {
"valid": true
}
}
```

2301
website/content/api-docs/secret/transform.mdx
View file

File diff suppressed because it is too large Load diff

2151
website/content/api-docs/secret/transit.mdx
View file

File diff suppressed because it is too large Load diff

97
website/content/api-docs/system/activation-flags.mdx
View file

@ -1,97 +0,0 @@
---
layout: api
page_title: /sys/activation-flags - HTTP API
description: The `/sys/activation-flags` endpoints are used to enable features that are gated by a one-time flag.
---
> [!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/activation-flags`
@include 'alerts/enterprise-only.mdx'
@include 'alerts/restricted-root.mdx'
Use the `/sys/activation-flags` endpoints to read and manage Vault
features that are gated by one-time flags. Gated features are
blocked and return errors until activated. Once removed, you cannot
un-activate gated features.
## ReadActivationFlags
ReadActivationFlags is an unauthenticated endpoint that returns information
about gated features and their activation status as two lists: `activated` and
`unactivated`. The activated list contains features ready to be used. The
unactivated list contains **available** but gated features. It filters out those
which are already active within your Vault instance.
| Method | Path |
| :----- | :---------------------- |
| `GET` | `/sys/activation-flags` |
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/sys/activation-flags
```
### Sample response
```json
{
"request_id": "9f70548c-a039-24a6-147d-7fa43698e044",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"activated": [],
"unactivated": [
"secrets-sync"
]
},
"warnings": null
}
```
## WriteActivationFlags
WriteActivationFlags unblocks and enables gated Vault features.
| Method | Path |
| :----- | :---------------------------------------- |
| `PUT` | `/sys/activation-flags/:feature/activate` |
### URL parameters
- `feature` `(string: <required>)` Feature key from ReadActivationFlags indicating the feature to activate.
### Sample request
```shell-session
$ curl \
--request PUT \
--header "X-Vault-Token: $VAULT_TOKEN" \
http://127.0.0.1:8200/v1/sys/activation-flags/secrets-sync/activate
```
### Sample response
```json
{
"request_id": "7636e655-e11d-e2aa-8286-bd38c1d9c600",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"activated": [
"secrets-sync"
],
"unactivated": []
},
"warnings": null,
"mount_type": "system"
}
```

67
website/content/api-docs/system/audit-hash.mdx
View file

@ -1,67 +0,0 @@
---
layout: api
page_title: /sys/audit-hash - HTTP API
description: |-
The `/sys/audit-hash` endpoint is used to hash data using an audit device's
hash function and salt.
---
> [!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/audit-hash`
@include 'alerts/restricted-admin.mdx'
The `/sys/audit-hash` endpoint is used to calculate the hash of the data used by
an audit device's hash function and salt. This can be used to search audit logs
for a hashed value when the original value is known.
## Calculate hash
This endpoint hashes the given input data with the specified audit device's
hash function and salt. This endpoint can be used to discover whether a given
plaintext string (the `input` parameter) appears in the audit log in obfuscated
form.
The audit log records requests and responses. Since the Vault API is JSON-based,
any binary data returned from an API call (such as a DER-format certificate) is
base64-encoded by the Vault server in the response. As a result such information
should also be base64-encoded to supply into the `input` parameter.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/sys/audit-hash/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the audit device to
generate hashes for. This is part of the request URL.
- `input` `(string: <required>)` – Specifies the input string to hash.
### Sample payload
```json
{
"input": "my-secret-vault"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/audit-hash/example-audit
```
### Sample response
```json
{
"hash": "hmac-sha256:08ba35..."
}
```

139
website/content/api-docs/system/audit.mdx
View file

@ -1,139 +0,0 @@
---
layout: api
page_title: /sys/audit - HTTP API
description: The `/sys/audit` endpoint is used to enable and disable audit devices.
---
> [!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/audit`
@include 'alerts/restricted-root.mdx'
The `/sys/audit` endpoint is used to list, enable, and disable audit devices.
Audit devices must be enabled before use, and more than one device may be
enabled at a time.
## List enabled audit devices
This endpoint lists only the enabled audit devices (it does not list all
available audit devices).
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
|:-------|:-------------|
| `GET` | `/sys/audit` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/audit
```
### Sample response
```javascript
{
"file": {
"type": "file",
"description": "Store logs in a file",
"options": {
"file_path": "/var/log/vault.log"
}
}
}
```
## Enable audit device
This endpoint enables a new audit device at the supplied path. The path can be a
single word name or a more complex, nested path.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
|:-------|:-------------------|
| `POST` | `/sys/audit/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path in which to enable the audit
device. This is part of the request URL.
- `description` `(string: "")` – Specifies a human-friendly description of the
audit device.
- `options` `(map<string|string>: nil)` – Specifies configuration options to pass to the audit device itself.
There are a set of [common options](#common-configuration-options)
which can be applied to all types of audit device.
For more details, please see the relevant page for an audit device `type`,
under [Audit Devices docs](/vault/docs/audit).
- `type` `(string: <required>)` – Specifies the type of the audit device.
Valid types are `file`, `socket` and `syslog`.
Additionally, the following options are allowed in Vault Community Edition, but
relevant functionality is only supported in Vault Enterprise:
- `local` `(bool: false)` – Applies exclusively to performance replication. Specifies if the audit device is local within the cluster only. Local
audit devices are not replicated nor (if a secondary) removed by replication.
#### Common configuration options
@include 'audit-options-common.mdx'
### Sample payload
```json
{
"type": "file",
"options": {
"file_path": "/var/log/vault/log"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/audit/example-audit
```
## Disable audit device
This endpoint disables the audit device at the given path.
~> Note: Once an audit device is disabled, you will no longer be able to HMAC values
for comparison with entries in the audit logs. This is true even if you re-enable
the audit device at the same path, as a new salt will be created for hashing.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
|:---------|:-------------------|
| `DELETE` | `/sys/audit/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path of the audit device to
delete. This is part of the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/sys/audit/example-audit
```

397
website/content/api-docs/system/auth.mdx
View file

@ -1,397 +0,0 @@
---
layout: api
page_title: /sys/auth - HTTP API
description: The `/sys/auth` endpoint is used to manage auth methods in Vault.
---
> [!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/auth`
The `/sys/auth` endpoint is used to list, create, update, and delete auth
methods. Auth methods convert user or machine-supplied information into a
token which can be used for all future requests.
## List auth methods
This endpoint lists all enabled auth methods.
| Method | Path |
| :----- | :---------- |
| `GET` | `/sys/auth` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/auth
```
### Sample response
```json
{
"request_id": "9bc0fab8-d65c-3961-afe6-d05f50c5fd22",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"github/": {
"accessor": "auth_github_badd7fd0",
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
},
"deprecation_status": "supported",
"description": "",
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "github",
"uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
},
"token/": {
"accessor": "auth_token_bd90f507",
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
},
"description": "token based credentials",
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "token",
"uuid": "e162baec-721b-7657-7913-c960df402f8a"
}
},
"warnings": null
}
```
## Enable auth method
This endpoint enables a new auth method. After enabling, the auth method can
be accessed and configured via the auth path specified as part of the URL. This
auth path will be nested under the `auth` prefix.
For example, enable the "foo" auth method will make it accessible at
`/auth/foo`.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
| :----- | :---------------- |
| `POST` | `/sys/auth/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path in which to enable the auth
method. This is part of the request URL.
!> **NOTE:** Use ASCII printable characters to specify the desired path.
- `description` `(string: "")` – Specifies a human-friendly description of the
auth method.
- `type` `(string: <required>)` – Specifies the name of the authentication
method type, such as "github" or "token".
- `config` `(map<string|string>: nil)` – Specifies configuration options for
this auth method. These are the possible values:
- `default_lease_ttl` `(string: "")` - The default lease duration, specified
as a string duration like "5s" or "30m".
- `max_lease_ttl` `(string: "")` - The maximum lease duration, specified as a
string duration like "5s" or "30m".
- `audit_non_hmac_request_keys` `(array: [])` - List of keys that will not be
HMAC'd by audit devices in the request data object.
- `audit_non_hmac_response_keys` `(array: [])` - List of keys that will not be
HMAC'd by audit devices in the response data object.
- `listing_visibility` `(string: "")` - Specifies whether to show this mount
in the UI-specific listing endpoint. Valid values are `"unauth"` or `"hidden"`,
with the default `""` being equivalent to `"hidden"`.
- `passthrough_request_headers` `(array: [])` - List of headers to allow
and pass from the request to the plugin.
- `allowed_response_headers` `(array: [])` - List of headers to allow,
allowing a plugin to include them in the response.
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". If unspecified, the server will select any matching
unversioned plugin that may have been registered, the latest versioned plugin
registered, or a built-in plugin in that order of precedence.
- `identity_token_key` `(string: "")` - The key to use for signing plugin workload
identity tokens. If not provided, this will default to Vault's OIDC
[default key](/vault/docs/concepts/oidc-provider#keys).
Additionally, the following options are allowed in Vault open-source, but
relevant functionality is only supported in Vault Enterprise:
- `local` `(bool: false)` – Specifies if the auth method is local only. Local
auth methods are not replicated nor (if a secondary) removed by replication.
Local auth mounts also generate entities for tokens issued. The entity will
be replicated across clusters and the aliases generated on the local auth
mount will be local to the cluster. Entities created by local auth mounts
are still replicated to other clusters, however it is possible to prevent
data pertaining to the local auth mount, including related aliases, from being
replicated by omitting them from the entity metadata.
~> ** Warning:** Remember, policies when using replication secondaries are
validated by the local cluster. An administrator that can set up a local auth
method mount can assign policies to tokens that are valid on the replication
primary if a request is forwarded. Never give untrusted administrators the
ability to assign policies or configure authentication methods.
- `seal_wrap` `(bool: false)` - Enable seal wrapping for the mount, causing
values stored by the mount to be wrapped by the seal's encryption capability.
### Sample payload
```json
{
"type": "github",
"description": "Login with GitHub"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/auth/my-auth
```
## Read auth method configuration
This endpoints returns the configuration of the auth method at the given path.
_This endpoint requires `sudo` capability on the final path, but the same
functionality can be achieved without `sudo` via `sys/mounts/auth/[auth-path]`._
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
| :----- | :---------------- |
| `GET` | `/sys/auth/:path` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/auth/my-auth
```
### Sample response
```json
{
"request_id": "8d2a1e33-4c00-46a5-f50d-4dc5f5d96f12",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"accessor": "auth_github_badd7fd0",
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
},
"deprecation_status": "supported",
"description": "",
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "github",
"uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
},
"warnings": null
}
```
## Disable auth method
This endpoint disables the auth method at the given auth path.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
| :------- | :---------------- |
| `DELETE` | `/sys/auth/:path` |
### Parameters
- `path` `(string: <required>)` – Specifies the path to disable. This is part of
the request URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/sys/auth/my-auth
```
## Read auth method tuning
This endpoint reads the given auth path's configuration. _This endpoint requires
`sudo` capability on the final path, but the same functionality can be achieved
without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `/sys/auth/:path/tune` |
### Parameters
- `path` `(string: <required>)` – Specifies the path in which to tune.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
```
### Sample response
```json
{
"default_lease_ttl": 2764800,
"description": "",
"force_no_cache": false,
"max_lease_ttl": 2764800,
"token_type": "default-service"
}
```
## Tune auth method
Tune configuration parameters for a given auth path. _This endpoint
requires `sudo` capability on the final path, but the same functionality
can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/sys/auth/:path/tune` |
### Parameters
- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. If set on
a specific auth path, this overrides the global default.
- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. If set on a
specific auth path, this overrides the global default.
- `description` `(string: "")` – Specifies the description of the mount. This
overrides the current stored value, if any.
- `audit_non_hmac_request_keys` `(array: [])` - Specifies the list of keys
that will not be HMAC'd by audit devices in the request data object.
- `audit_non_hmac_response_keys` `(array: [])` - Specifies the list of keys
that will not be HMAC'd by audit devices in the response data object.
- `listing_visibility` `(string: "")` - Specifies whether to show this mount
in the UI-specific listing endpoint. Valid values are `"unauth"` or `"hidden"`,
with the default `""` being equivalent to `"hidden"`.
- `passthrough_request_headers` `(array: [])` - List of headers to allow
and pass from the request to the plugin.
- `allowed_response_headers` `(array: [])` - List of headers to allow,
allowing a plugin to include them in the response.
- `token_type` `(string: "")` – Specifies the type of tokens that should be
returned by the mount. The following values are available:
- `default-service`: Unless the auth method requests a different type, issue
service tokens
- `default-batch`: Unless the auth method requests a different type, issue
batch tokens
- `service`: Override any auth method preference and always issue service
tokens from this mount
- `batch`: Override any auth method preference and always issue batch tokens
from this mount
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.
- `user_lockout_config` `(map<string|string>: nil)` – Specifies the user lockout configuration
for the mount. User lockout feature was added in Vault 1.13. These are the possible values:
- `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after
which the user is locked out, specified as a string like "15".
- `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out,
specified as a string duration like "5s" or "30m".
- `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is
reset with no failed login attempts, specified as a string duration like "5s" or "30m".
- `lockout_disable` `(bool: false)` - Disables the user lockout feature for this mount
if set to true.
### Sample payload
```json
{
"default_lease_ttl": 1800,
"max_lease_ttl": 86400,
"audit_non_hmac_request_keys": ["client_nonce"],
"user_lockout_config":{
"lockout_threshold":"20",
"lockout_duration":"5m",
"lockout_counter_reset":"5m"
}
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
```

67
website/content/api-docs/system/capabilities-accessor.mdx
View file

@ -1,67 +0,0 @@
---
layout: api
page_title: /sys/capabilities-accessor - HTTP API
description: |-
The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of
the token associated with an accessor, on the given paths.
---
> [!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/capabilities-accessor`
The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of
the token associated with the given accessor. The capabilities returned will be
derived from the policies that are on the token, and from the policies to which
the token is entitled to through the entity and entity's group memberships.
## Query token accessor capabilities
This endpoint returns the capabilities of the token associated with the given
accessor, for the given path. Multiple paths are taken in at once and the
capabilities of the token associated with the given accessor for each path is
returned. For backwards compatibility, if a single path is supplied, a
`capabilities` field will also be returned.
@include 'api/no-capabilities.mdx'
| Method | Path |
| :----- | :--------------------------- |
| `POST` | `/sys/capabilities-accessor` |
### Parameters
- `accessor` `(string: <required>)` – Accessor of the token for which
capabilities are being queried.
- `paths` `(list: <required>)` – Paths on which capabilities are being
queried.
### Sample payload
```json
{
"accessor": "abcd1234",
"paths": ["secret/foo"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/capabilities-accessor
```
### Sample response
```json
{
"capabilities": ["delete", "list", "read", "update"],
"secret/foo": ["delete", "list", "read", "update"]
}
```

63
website/content/api-docs/system/capabilities-self.mdx
View file

@ -1,63 +0,0 @@
---
layout: api
page_title: /sys/capabilities-self - HTTP API
description: |-
The `/sys/capabilities-self` endpoint is used to fetch the capabilities of
client token on the given paths.
---
> [!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/capabilities-self`
The `/sys/capabilities-self` endpoint is used to fetch the capabilities of the
token used to make the API call, on the given paths. The capabilities returned
will be derived from the policies that are on the token, and from the policies
to which the token is entitled to through the entity and entity's group
memberships.
## Query self capabilities
This endpoint returns the capabilities of client token on the given paths. The
client token is the Vault token with which this API call is made. Multiple
paths are taken in at once and the capabilities of the token for each path is
returned. For backwards compatibility, if a single path is supplied, a
`capabilities` field will also be returned.
@include 'api/no-capabilities.mdx'
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/sys/capabilities-self` |
### Parameters
- `paths` `(list: <required>)` – Paths on which capabilities are being queried.
### Sample payload
```json
{
"paths": ["secret/foo"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/capabilities-self
```
### Sample response
```json
{
"capabilities": ["delete", "list", "read", "update"],
"secret/foo": ["delete", "list", "read", "update"]
}
```

65
website/content/api-docs/system/capabilities.mdx
View file

@ -1,65 +0,0 @@
---
layout: api
page_title: /sys/capabilities - HTTP API
description: |-
The `/sys/capabilities` endpoint is used to fetch the capabilities of a token
on the given paths.
---
> [!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/capabilities`
The `/sys/capabilities` endpoint is used to fetch the capabilities of a token
on the given paths. The capabilities returned will be derived from the policies
that are on the token, and from the policies to which the token is entitled to
through the entity and entity's group memberships.
## Query token capabilities
This endpoint returns the list of capabilities of a given token on the given
paths. Multiple paths are taken in at once and the capabilities of the token
for each path is returned. For backwards compatibility, if a single path is
supplied, a `capabilities` field will also be returned.
@include 'api/no-capabilities.mdx'
| Method | Path |
| :----- | :------------------ |
| `POST` | `/sys/capabilities` |
### Parameters
- `paths` `(list: <required>)` – Paths on which capabilities are being queried.
- `token` `(string: <required>)` – Token for which capabilities are being
queried.
### Sample payload
```json
{
"token": "abcd1234",
"paths": ["secret/foo"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/capabilities
```
### Sample response
```json
{
"capabilities": ["delete", "list", "read", "update"],
"secret/foo": ["delete", "list", "read", "update"]
}
```

Some files were not shown because too many files have changed in this diff Show more