add usage examples for tokens and token roles

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");
+```

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]]

_Sidebar.md

@@ -5,4 +5,5 @@
 # [[Usage Examples|Usage]]
 * [[Connection|Usage Connection]]
 * [[Authorization|Usage Authorization]]
-* [[Secrets|Usage Secrets]]
+* [[Secrets|Usage Secrets]]
+* [[Tokens|Usage Tokens]]