Difficulty: beginner
Estimated Time: 10 minutes

Vault logo

This scenario supplements the Tokens guide.


Tokens are the core method for authentication within Vault. Tokens can be used directly or dynamically generated by the auth methods. Regardless, the clients need valid tokens to interact with Vault.

There are two types of tokens: service tokens and batch tokens. The service tokens are persisted; therefore, they can be renewed or revoked before reaching its time-to-live (TTL). On the other hand, batch tokens are not persisted. They are encrypted binary large objects (blobs) that carry enough information for them to be used for Vault actions. Therefore, batch tokens are extremely lightweight and scalable; however, they lack most of the flexibility and features of service tokens.

Service Tokens vs. Batch Tokens

As the number of machines and apps using Vault for secret management scales, Vault must manage the growing number of client tokens. The creation of service tokens can start affecting the Vault performance since they must be replicated across the primary and secondary clusters. On the other hand, batch tokens are neither persisted to disk nor live in memory, they are not a part of the data replication process.

Depending on the use case and the performance requirements, the batch tokens might work better than the service tokens or vice versa.

This tutorial focuses on the batch tokens. To learn more about service tokens, try Vault Token Lifecycle scenario.

This scenario demonstrated the characteristics of batch tokens introduced in Vault 1.0.


Vault Batch Tokens

Step 1 of 4

Create a Batch Token

Batch tokens are designed to be lightweight with limited flexibility. The following table highlights the difference.

Service Tokens Batch Tokens
Can be root tokens Yes No
Can create child tokens Yes No
Renewable Yes No
Can be periodic Yes No
Can have explicit Max TTL Yes No (always uses a fixed TTL)
Has accessors Yes No
Has Cubbyhole Yes No
Revoked with parent (if not orphan) Yes Stops Working
Dynamic secrets lease assignment Self Parent (if not orphan)
Can be used across Performance Replication clusters No Yes
Creation scales with performance standby node count No Yes
Cost Heavyweight; multiple storage writes per token creation Lightweight; no storage cost for token creation

Create a batch token

Login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

To create a batch token, you need to explicitly set the token type to be batch.

Execute the following command:

vault token create -type="batch"

Currently, you are logged in with root token; therefore, the child token inherits its creator's policy in absence of -policy flag.

Code: 400. Errors:

* batch tokens cannot be root tokens

Batch tokens cannot be root tokens. clear

Let's create a policy named, base.

vault policy write base base.hcl

To review the created policy:

vault policy read base

Now, create a batch token with a non-root policy attached and save it to token.txt file:

vault token create -type=batch -policy=base -format=json \
      | jq -r ".auth.client_token" > token.txt

Notice that the generated token value is much longer than the service tokens (token.txt). This is because batch tokens are encrypted by the Vault's barrier.

Let's view the generated batch token's properties:

vault token lookup $(cat token.txt)

The output look similar to the following:

Key                 Value
---                 -----
accessor            n/a
creation_time       1540592796
creation_ttl        768h
display_name        token
entity_id           n/a
expire_time         2018-11-27T14:26:36-08:00
explicit_max_ttl    0s
id                  b.AAAAAQKf5kVdMwjIwt4o49fDHIfEELolVEbz-rAzlKOlHTrGW_aZrFslOezTsk4JjuTwYtzNONARecYwJRjx59GQmiX6icA7gxnKKzsD3cPYtI10CHoH1GFAyGTN2K4gLIYeHBWdq6O2
issue_time          2018-10-26T15:26:36-07:00
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create
policies            [base default]
renewable           false
ttl                 767h59m46s
type                batch

Notice that the type is batch, and it does not have a token accessor. Also, the renewable parameter is set to false since batch tokens are NOT renewable.