From 5b709668b65a10e1ce4ee9ba5d47d5b7e274ea23 Mon Sep 17 00:00:00 2001
From: Stefan Kalscheuer <stefan@stklcode.de>
Date: Sun, 26 Apr 2020 17:36:43 +0200
Subject: [PATCH] add usage examples for tokens and token roles

---
 Usage-Tokens.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++
 Usage.md        |  1 +
 _Sidebar.md     |  3 ++-
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 Usage-Tokens.md

diff --git a/Usage-Tokens.md b/Usage-Tokens.md
new file mode 100644
index 0000000..b59c924
--- /dev/null
+++ b/Usage-Tokens.md
@@ -0,0 +1,52 @@
+# Java Vault Connector 
+
+## Usage Examples
+
+### Tokens
+
+The connector supports reading and writing of access tokens as well as token roles.
+While tokens basically are specialized secrets they have a well-documented API and several flags, s.t. they have been
+abstracted for comfortable and speaking use.
+
+#### Create, lookup and delete tokens
+
+```java
+ VaultConnector connector = ...;
+
+// Create token using the builder (more flags available).
+Token token = Token.builder()
+                   .withId("my-token")
+                   .withDisplayName("new test token")
+                   .withType(Token.Type.SERVICE)
+                   .withPolicies("pol1", "pol2")
+                   .build();
+
+ // Write token to Vault.
+vault.createToken(token);
+
+// Lookup token by ID
+TokenResponse tokenRes = vault.lookupToken("my-token");
+```
+
+#### Handle token roles
+
+```java
+// Create token role using the builder (more flags available).
+TokenRole role = TokenRole.builder()
+                          .forName("my-role")
+                          .renewable(true)
+                          .withTokenNumUses(42)
+                          .build();
+
+// Create the role.
+vault.createOrUpdateTokenRole(role);
+
+// Read a token role.
+TokenRoleResponse roleRes = vault.readTokenRole("another-role");
+
+// List available roles.
+List<String> roles = vault.listTokenRoles();
+
+// Delete a token role.
+vault.deleteTokenRole("obsolete-rule");
+```
diff --git a/Usage.md b/Usage.md
index 238430c..f3afd85 100644
--- a/Usage.md
+++ b/Usage.md
@@ -12,3 +12,4 @@ For a complete guide refer to the API docs.
 * [[Connection|Usage Connection]]
 * [[Authorization|Usage Authorization]]
 * [[Secrets|Usage Secrets]]
+* [[Secrets|Usage Tokens]]
diff --git a/_Sidebar.md b/_Sidebar.md
index 9e7a161..f6bdc03 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -5,4 +5,5 @@
 # [[Usage Examples|Usage]]
 * [[Connection|Usage Connection]]
 * [[Authorization|Usage Authorization]]
-* [[Secrets|Usage Secrets]]
\ No newline at end of file
+* [[Secrets|Usage Secrets]]
+* [[Tokens|Usage Tokens]]