9 KiB
9 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| docs | Auth Backend: Token | docs-auth-token | The token store auth backend is used to authenticate using tokens. |
Auth Backend: Token
The token backend is the only auth backend that is built-in and
automatically available at /auth/token as well as with first-class
built-in CLI methods such as vault token-create. It allows users to
authenticate using a token, as well to create new tokens, revoke
secrets by token, and more.
When any other auth backend returns an identity, Vault core invokes the token backend to create a new unique token for that identity.
The token store can also be used to bypass any other auth backend: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation.
Please see the token concepts page dedicated to tokens.
Authentication
Via the CLI
$ vault auth <token>
...
Via the API
The token is set directly as a header for the HTTP API. The name of the header should be "X-Vault-Token" and the value should be the token.
API
/auth/token/create[-orphan]
POST
- Description
- 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).
- Method
- POST
- URL
- `/auth/token/create[-orphan]`
- Parameters
-
- id optional The ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated UUID.
- policies optional A list of policies for the token. This must be a subset of the policies belonging to the token making the request, unless root. If not specified, defaults to all the policies of the calling token.
- meta optional A map of string to string valued metadata. This is passed through to the audit backends.
- no_parent optional If true and set by a root caller, the token will not have the parent token of the caller. This creates a token with no parent.
- no_default_profile optional If true the `default` profile will not be a part of this token's policy set.
- lease optional DEPRECATED; use "ttl" instead.
- ttl optional 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](/docs/config/index.html), or indefinitely if the root policy is used.
- display_name optional The display name of the token. Defaults to "token".
- num_uses optional 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.
- Returns
-
```javascript { "auth": { "client_token": "ABCD", "policies": ["web", "stage"], "metadata": {"user": "armon"}, "lease_duration": 3600, "renewable": true, } } ```
/auth/token/lookup-self
GET
- Description
- Returns information about the current client token.
- Method
- GET
- Parameters
- None
- Returns
-
```javascript { "data": { "id": "ClientToken", "policies": ["web", "stage"], "path": "auth/github/login", "meta": {"user": "armon", "organization": "hashicorp"}, "display_name": "github-armon", "num_uses": 0, } } ```
/auth/token/lookup/
GET
- Description
- Returns information about the current client token.
- Method
- GET
- URL
- `/auth/token/lookup/`
- Parameters
- None
- Returns
-
```javascript { "data": { "id": "ClientToken", "policies": ["web", "stage"], "path": "auth/github/login", "meta": {"user": "armon", "organization": "hashicorp"}, "display_name": "github-armon", "num_uses": 0, } } ```
/auth/token/revoke/
POST
- Description
- Revokes a token and all child tokens. When the token is revoked, all secrets generated with it are also revoked.
- Method
- POST
- URL
- `/auth/token/revoke/`
- Parameters
- None
- Returns
- `204` response code.
/auth/token/revoke-self/
POST
- Description
- Revokes the token used to call it and all child tokens. When the token is revoked, all secrets generated with it are also revoked.
- Method
- POST
- URL
- `/auth/token/revoke-self`
- Parameters
- None
- Returns
- `204` response code.
/auth/token/revoke-orphan/
POST
- Description
- 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/`.
- Method
- POST
- URL
- `/auth/token/revoke-orphan/`
- Parameters
- None
- Returns
- `204` response code.
/auth/token/revoke-prefix/
POST
- Description
- 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.
- Method
- POST
- URL
- `/auth/token/revoke-prefix/`
- Parameters
- None
- Returns
- `204` response code.
/auth/token/renew-self
POST
- Description
- Renews a lease associated with the callign 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
- POST
- URL
- `/auth/token/renew-self`
- Parameters
-
- increment optional An optional requested lease increment can be provided. This increment may be ignored.
- Returns
-
```javascript { "auth": { "client_token": "ABCD", "policies": ["web", "stage"], "metadata": {"user": "armon"}, "lease_duration": 3600, "renewable": true, } } ```
/auth/token/renew/
POST
- Description
- 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
- POST
- URL
- `/auth/token/renew/`
- Parameters
-
- increment optional An optional requested lease increment can be provided. This increment may be ignored.
- Returns
-
```javascript { "auth": { "client_token": "ABCD", "policies": ["web", "stage"], "metadata": {"user": "armon"}, "lease_duration": 3600, "renewable": true, } } ```