# vhsm token

The `vhsm token` command manages authentication tokens in vHSM. Users can create, lookup, renew, and revoke tokens.

### **Usage**

```
vhsm token <subcommand> [options] [arguments]
```

### **Subcommands**

| Command                               | Description                                         |
| ------------------------------------- | --------------------------------------------------- |
| [`capabilities`](#token-capabilities) | Print the capabilities of a token for a given path. |
| [`create`](#create-a-new-token)       | Create a new authentication token.                  |
| [`lookup`](#token-lookup)             | Retrieve information about a token.                 |
| [`renew`](#renew-a-token)             | Extend the lease of a token.                        |
| [`revoke`](#revoke-a-token)           | Revoke a token and its children.                    |

### **`token capabilities`**

Fetches the capabilities of a token for a specified path.

#### **Example**

List capabilities for the current token on the `secret/foo` path:

```
vhsm token capabilities secret/foo
```

**Output**

```
read
```

List capabilities for a specific token on the `database/creds/readonly` path:

```
vhsm token capabilities 96ddf4bc-d217-f3ba-f9bd-017055595017 database/creds/readonly
```

**Output**

```
deny
```

### **`token create`**

Creates a new authentication token. This token will inherit policies from the currently authenticated token unless explicitly specified.

#### **Examples**

Create a token with specific policies:

```
vhsm token create -policy=my-policy -policy=other-policy
```

Create a periodic token:

```
vhsm token create -period=30m
```

#### **Options**

| Option              | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `-policy`           | Attach a policy to the token. Multiple policies can be added. |
| `-ttl`              | Set an initial TTL for the token.                             |
| `-renewable`        | Allow token renewal (default: true).                          |
| `-explicit-max-ttl` | Set a hard maximum lifetime for the token.                    |

### **`token lookup`**

Retrieves information about a token. If no token is provided, the currently authenticated token is used.

#### **Examples**

Get information about the current token:

```
vhsm token lookup
```

Get information about a specific token:

```
vhsm token lookup 96ddf4bc-d217-f3ba-f9bd-017055595017
```

Get information via a token's accessor:

```
vhsm token lookup -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da
```

### **`token renew`**

Extends the lease of a token. If no token is provided, the currently authenticated token is used.

#### **Examples**

Renew a specific token:

```
vhsm token renew 96ddf4bc-d217-f3ba-f9bd-017055595017
```

Renew the currently authenticated token:

```
vhsm token renew
```

Renew a token with a specific increment:

```
vhsm token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017
```

#### **Options**

| **Option**   | **Description**                       |
| ------------ | ------------------------------------- |
| `-increment` | Request a specific renewal increment. |

### **`token revoke`**

Revokes authentication tokens and their children.

#### **Examples**

Revoke a specific token and its children:

```
vhsm token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017
```

Revoke a token but leave its children:

```
vhsm token revoke -mode=orphan 96ddf4bc-d217-f3ba-f9bd-017055595017
```

Revoke a token using an accessor:

```
vhsm token revoke -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da
```

#### **Options**

| Option      | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `-accessor` | Treat argument as an accessor instead of a token.            |
| `-mode`     | Specify revocation mode (`orphan` to leave children intact). |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/cli/authentication-and-authorization/vhsm-token.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.