token

The token command groups subcommands for interacting with tokens. Users can create, lookup, renew, and revoke tokens.

For more information on tokens, please see the token concepts page.

Examples

Create a new token:

$ vault token create

Revoke a token:

$ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017

Renew a token:

$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017

Usage

Usage: vault token <subcommand> [options] [args]

  # ...

Subcommands:
    capabilities    Print capabilities of a token on a path
    create          Create a new token
    lookup          Display information about a token
    renew           Renew a token lease
    revoke          Revoke a token and its children

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

token capabilities

The token capabilities command fetches the capabilities of a token for a given path.

If a TOKEN is provided as an argument, this command uses the "/sys/capabilities" endpoint and permission. If no TOKEN is provided, this command uses the "/sys/capabilities-self" endpoint and permission with the locally authenticated token.

Examples

List capabilities for the local token on the "secret/foo" path:

$ vault token capabilities secret/foo
read

List capabilities for a token on the "cubbyhole/foo" path:

$ vault token capabilities 96ddf4bc-d217-f3ba-f9bd-017055595017 database/creds/readonly
deny

Usage

The following flags are available in addition to the standard set of flags included on all commands.

Output options

• -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

token create

The token create command creates a new token that can be used for authentication. This token will be created as a child of the currently authenticated token. The generated token will inherit all policies and permissions of the currently authenticated token unless you explicitly define a subset list policies to assign to the token.

A ttl can also be associated with the token. If a ttl is not associated with the token, then it cannot be renewed. If a ttl is associated with the token, it will expire after that amount of time unless it is renewed.

Metadata associated with the token (specified with -metadata) is written to the audit log when the token is used.

If a role is specified, the role may override parameters specified here.

Examples

Create a token attached to specific policies:

$ vault token create -policy=my-policy -policy=other-policy
Key                Value
---                -----
token              95eba8ed-f6fc-958a-f490-c7fd0eda5e9e
token_accessor     882d4a40-3796-d06e-c4f0-604e8503750b
token_duration     768h
token_renewable    true
token_policies     [default my-policy other-policy]

Create a periodic token:

$ vault token create -period=30m
Key                Value
---                -----
token              fdb90d58-af87-024f-fdcd-9f95039e353a
token_accessor     4cd9177c-034b-a004-c62d-54bc56c0e9bd
token_duration     30m
token_renewable    true
token_policies     [my-policy]

Usage

The following flags are available in addition to the standard set of flags included on all commands.

Output options

• -field (string: "") - Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.

• -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

• -display-name (string: "") - Name to associate with this token. This is a non-sensitive value that can be used to help identify created secrets (e.g. prefixes).

• -entity-alias (string: "") - Name of the entity alias to associate with during token creation. Only works in combination with -role 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.

• -explicit-max-ttl (duration: "") - Explicit maximum lifetime for the token. Unlike normal TTLs, the maximum TTL is a hard limit and cannot be exceeded. Uses duration format strings.

• -id (string: "") - Value for the token. By default, this is an auto-generated value. Specifying this value requires sudo permissions.

• -metadata (k=v: "") - Arbitrary key=value metadata to associate with the token. This metadata will show in the audit log when the token is used. This can be specified multiple times to add multiple pieces of metadata.

• -no-default-policy (bool: false) - Detach the "default" policy from the policy set for this token.

• -orphan (bool: false) - Create the token with no parent. This prevents the token from being revoked when the token which created it expires. Setting this value requires sudo permissions.

• -period (duration: "") - If specified, every renewal will use the given period. Periodic tokens do not expire as long as they are actively being renewed (unless -explicit-max-ttl is also provided). Setting this value requires sudo permissions. Uses duration format strings.

• -policy (string: "") - Name of a policy to associate with this token. This can be specified multiple times to attach multiple policies.

• -renewable (bool: true) - Allow the token to be renewed up to it's maximum TTL.

• -role (string: "") - Name of the role to create the token against. Specifying -role may override other arguments. The locally authenticated Vault token must have permission for auth/token/create/<role>.

• -ttl (duration: "") - Initial TTL to associate with the token. Token renewals may be able to extend beyond this value, depending on the configured maximumTTLs. Uses duration format strings.

• -type (string: "service") - The type of token to create. Can be "service" or "batch".

• -use-limit (int: 0) - Number of times this token can be used. After the last use, the token is automatically revoked. By default, tokens can be used an unlimited number of times until their expiration.

• -wrap-ttl (duration: "") - Wraps the response in a cubbyhole token with the requested TTL. The response is available via the "vault unwrap" command. The TTL is specified as a numeric string with suffix like "30s" or "5m". This can also be specified via the VAULT_WRAP_TTL environment variable.

token lookup

The token lookup displays information about a token or accessor. If a TOKEN is not provided, the locally authenticated token is used.

Examples

Get information about the locally authenticated token (this uses the /auth/token/lookup-self endpoint and permission):

$ vault token lookup

Get information about a particular token (this uses the /auth/token/lookup endpoint and permission):

$ vault token lookup 96ddf4bc-d217-f3ba-f9bd-017055595017

Get information about a token via its accessor:

$ vault token lookup -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da

Usage

The following flags are available in addition to the standard set of flags included on all commands.

Output options

• -format (default: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

• -accessor (bool: false) - Treat the argument as an accessor instead of a token. When this option is selected, the output will NOT include the token.

token renew

The token renew renews a token's lease, extending the amount of time it can be used. If a TOKEN is not provided, the locally authenticated token is used. Lease renewal will fail if the token is not renewable, the token has already been revoked, or if the token has already reached its maximum TTL.

Examples

Renew a token (this uses the /auth/token/renew endpoint and permission):

$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017

Renew the currently authenticated token (this uses the /auth/token/renew-self endpoint and permission):

$ vault token renew

Renew a token requesting a specific increment value:

$ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017

Usage

The following flags are available in addition to the standard set of flags included on all commands.

Output options

• -format (default: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

• -increment (duration: "") - Request a specific increment for renewal. Vault will not honor this request for periodic tokens. If not supplied, Vault will use the default TTL. This is specified as a numeric string with suffix like "30s" or "5m". This is aliased as "-i".

token revoke

The token revoke revokes authentication tokens and their children. If a TOKEN is not provided, the locally authenticated token is used. The -mode flag can be used to control the behavior of the revocation.

Examples

Revoke a token and all the token's children:

$ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017
Success! Revoked token (if it existed)

Revoke a token leaving the token's children:

$ vault token revoke -mode=orphan 96ddf4bc-d217-f3ba-f9bd-017055595017
Success! Revoked token (if it existed)

Revoke a token by accessor:

$ vault token revoke -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da
Success! Revoked token (if it existed)

Usage

The following flags are available in addition to the standard set of flags included on all commands.

• -accessor (bool: false) - Treat the argument as an accessor instead of a token.

• -mode (string: "") - Type of revocation to perform. If unspecified, Vault will revoke the token and all of the token's children. If "orphan", Vault will revoke only the token, leaving the children as orphans. If "path", tokens created from the given authentication path prefix are deleted along with their children.

• -self - Perform the revocation on the currently authenticated token.