mirror of
https://github.com/hashicorp/vault.git
synced 2026-06-08 16:24:51 -04:00
Update token documentation
This commit is contained in:
Jeff Mitchell
parent
42501e388b
commit
6e8033b5bd
1 changed files with 227 additions and 55 deletions
|
|
@ -40,24 +40,29 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
|
||||
## API
|
||||
|
||||
### /auth/token/create[-orphan]
|
||||
### /auth/token/create
|
||||
### /auth/token/create-orphan
|
||||
### /auth/token/create/[role_name]
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Creates a new token. Certain options are only available to
|
||||
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).
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/create[-orphan]`</dd>
|
||||
<dt>URLs</dt>
|
||||
<dd>`/auth/token/create`</dd>
|
||||
<dd>`/auth/token/create-orphan`</dd>
|
||||
<dd>`/auth/token/create/<role_name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
|
|
@ -116,7 +121,7 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
<span class="param-flags">optional</span>
|
||||
The maximum uses for the given token. This can be used to create
|
||||
a one-time-token or limited use token. Defaults to 0, which has
|
||||
no limit to number of uses.
|
||||
no limit to the number of uses.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
|
@ -124,7 +129,7 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
|
|
@ -209,9 +214,103 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/renew-self
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/renew-self`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An optional requested lease increment can be provided. This
|
||||
increment may be ignored.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/renew/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/renew/<token>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An optional requested lease increment can be provided. This
|
||||
increment may be ignored.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/revoke/
|
||||
#### POST
|
||||
|
|
@ -272,9 +371,10 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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/`.
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
|
|
@ -302,6 +402,7 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
Revokes all tokens generated at a given prefix, along with child tokens,
|
||||
and all secrets generated using those tokens. Uses include revoking all
|
||||
tokens generated by a credential backend during a suspected compromise.
|
||||
This is a root-protected endpoint.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
|
|
@ -320,33 +421,50 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/renew-self
|
||||
#### POST
|
||||
### /auth/token/roles/[role_name]
|
||||
|
||||
#### DELETE
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
Deletes the named role.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/renew-self`</dd>
|
||||
<dd>`/auth/token/roles/<role_name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An optional requested lease increment can be provided. This
|
||||
increment may be ignored.
|
||||
</li>
|
||||
</ul>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
#### GET
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Fetches the named role configuration.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/roles/<role_name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
|
|
@ -354,45 +472,35 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
"data": {
|
||||
"period": 3600,
|
||||
"allowed_policies": ["web", "stage"],
|
||||
"orphan": true,
|
||||
"prefix": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/renew/
|
||||
#### POST
|
||||
#### LIST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
Lists available roles.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/renew/<token>`</dd>
|
||||
<dd>`/auth/token/roles?list=true`<dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An optional requested lease increment can be provided. This
|
||||
increment may be ignored.
|
||||
</li>
|
||||
</ul>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
|
|
@ -400,15 +508,79 @@ of the header should be "X-Vault-Token" and the value should be the token.
|
|||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
"data": {
|
||||
"keys": ["role1", "role2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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 `revoke-prefix`
|
||||
endpoint.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/roles/<role_name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">allowed_policies</span>
|
||||
<span class="param-flags">optional</span>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">orphan</span>
|
||||
<span class="param-flags">optional</span>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">period</span>
|
||||
<span class="param-flags">optional</span>
|
||||
If set, tokens created against this role will <i>not</i> have a maximum
|
||||
lifetime. Instead, they will have a fixed TTL that is refreshed with
|
||||
each renewal. So long as they continue to be renewed, they will never
|
||||
expire. The parameter is an integer duration of seconds or a duration
|
||||
string (e.g. `"72h"`).
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">prefix</span>
|
||||
<span class="param-flags">optional</span>
|
||||
If set, tokens created against this role will have the given prefix 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
|
||||
prefix can be changed, allowing new callers to have the new prefix as
|
||||
part of their path, and then tokens with the old prefix can be revoked
|
||||
via `revoke-prefix`.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A `204` return code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue