> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens

> Create and manage Vault access tokens

Vault Tokens are the primary authentication method for accessing secrets. Every request to Vault requires a valid token. Tokens can have policies attached, time limits, and usage restrictions.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Authentication" icon="fingerprint">
    Tokens authenticate requests to Vault. No token means no access.
  </Card>

  <Card title="Policies" icon="shield-check">
    Tokens inherit permissions from attached policies. More policies = more access.
  </Card>

  <Card title="TTL (Time To Live)" icon="clock">
    Tokens expire after their TTL. Renewable tokens can extend their lifetime.
  </Card>

  <Card title="Accessors" icon="key">
    Public identifiers for tokens. Used to manage tokens without exposing the secret.
  </Card>
</CardGroup>

## Token Properties

| Property         | Description                                         |
| ---------------- | --------------------------------------------------- |
| **Accessor**     | Public identifier for the token (safe to log/store) |
| **Display Name** | Human-readable label for identification             |
| **Policies**     | List of policies granting permissions               |
| **TTL**          | Time until token expires                            |
| **Renewable**    | Whether the token can be renewed                    |
| **Token Type**   | Service (default) or batch                          |
| **Num Uses**     | Maximum number of times token can be used           |

## Required Permissions

| Action              | Permission                      |
| ------------------- | ------------------------------- |
| View tokens         | `iam:project:cicd:vault:read`   |
| Create/Renew tokens | `iam:project:cicd:vault:write`  |
| Revoke tokens       | `iam:project:cicd:vault:delete` |

## How to Create a Token

<Steps>
  <Step title="Select Vault Instance">
    Choose the target Vault instance from the dropdown.
  </Step>

  <Step title="Click Create Token">
    Click the **Create Token** button.
  </Step>

  <Step title="Configure Token Information">
    * **Display Name**: Human-readable identifier (e.g., `ci-pipeline-token`)
    * **Policies**: Comma-separated list of policies (e.g., `default, app-read`)
  </Step>

  <Step title="Set Time & Limits">
    * **TTL**: Token lifetime (e.g., `24h`, `7d`, `30d`)
    * **Period**: For periodic tokens (renewable indefinitely)
    * **Max TTL**: Absolute maximum lifetime
    * **Num Uses**: Limit usage count (0 = unlimited)
    * **Renewable**: Toggle to allow renewal
  </Step>

  <Step title="Add Metadata (Optional)">
    Add JSON metadata for tracking:

    ```json theme={null}
    {
      "created_by": "admin",
      "environment": "production",
      "purpose": "CI/CD pipeline"
    }
    ```
  </Step>

  <Step title="Create">
    Click **Create Token**. The token is generated.
  </Step>

  <Step title="Copy Token Immediately">
    The token value is shown **only once**. Copy and store it securely before closing the dialog.
  </Step>
</Steps>

<Warning>
  The token value is displayed only once at creation. If you lose it, you must create a new token. There is no way to retrieve an existing token's value.
</Warning>

## TTL Format Reference

| Format   | Example | Meaning            |
| -------- | ------- | ------------------ |
| Hours    | `24h`   | 24 hours           |
| Days     | `7d`    | 7 days             |
| Weeks    | `2w`    | 2 weeks            |
| Months   | `1M`    | 1 month            |
| Years    | `1y`    | 1 year             |
| Combined | `1d12h` | 1 day and 12 hours |

## Token Types

### Service Tokens (Default)

* Stored in Vault's storage backend
* Can create child tokens
* Support all token features
* Best for: Long-lived applications, users

### Batch Tokens

* Not stored in Vault (stateless)
* Cannot create child tokens
* Cannot be renewed
* Best for: High-performance, short-lived operations

## How to Renew a Token

Renewable tokens can extend their TTL before expiration.

<Steps>
  <Step title="Find the Token">
    Locate the token in the list by accessor or display name.
  </Step>

  <Step title="Click Renew">
    Click the refresh icon on the token row.
  </Step>

  <Step title="Confirm">
    Confirm the renewal. The token's TTL is extended.
  </Step>
</Steps>

<Info>
  Renewal extends the TTL by the token's original TTL duration, up to the explicit max TTL if set. Non-renewable tokens cannot be renewed.
</Info>

## How to Revoke a Token

Revoked tokens immediately become invalid.

<Steps>
  <Step title="Find the Token">
    Locate the token in the list.
  </Step>

  <Step title="Click Revoke">
    Click the trash icon on the token row.
  </Step>

  <Step title="Confirm">
    Confirm the revocation. The token is permanently invalidated.
  </Step>
</Steps>

<Warning>
  Revoking a token also revokes all child tokens created by it. This action cannot be undone.
</Warning>

## Common Token Patterns

### CI/CD Pipeline Token

```
Display Name: ci-pipeline-prod
Policies: ci-read-secrets, deploy-prod
TTL: 1h
Renewable: Yes
Num Uses: 0 (unlimited)
```

Short-lived but renewable for long-running pipelines.

### Application Service Token

```
Display Name: myapp-backend
Policies: app-secrets-read
TTL: 24h
Renewable: Yes
Period: 12h
```

Periodic token that renews indefinitely as long as the app is running.

### One-Time Bootstrap Token

```
Display Name: initial-setup
Policies: bootstrap-admin
TTL: 30m
Renewable: No
Num Uses: 1
```

Single-use token for initial configuration.

### Developer Token

```
Display Name: dev-john-doe
Policies: dev-read-only
TTL: 8h
Renewable: Yes
Max TTL: 7d
```

Daily token that can be renewed up to a week.

## Metadata Best Practices

Use metadata for:

```json theme={null}
{
  "created_by": "john.doe@company.com",
  "team": "platform",
  "environment": "production",
  "purpose": "Database credential rotation",
  "ticket": "JIRA-1234"
}
```

Metadata helps with:

* Audit trail and compliance
* Token ownership tracking
* Debugging and troubleshooting
* Automated cleanup policies

## Troubleshooting

<AccordionGroup>
  <Accordion title="Token not appearing in list" icon="circle-question">
    * Refresh the page or click the refresh button
    * Tokens may take a moment to propagate
    * Verify you're viewing the correct Vault instance
  </Accordion>

  <Accordion title="Cannot create token" icon="circle-question">
    * You need write permission for Vault tokens
    * The Vault instance must be active and reachable
    * Check that policies specified exist
  </Accordion>

  <Accordion title="Token expired immediately" icon="circle-question">
    * TTL may have been set too short
    * Server time may be out of sync
    * Max TTL on the auth method may limit token lifetime
  </Accordion>

  <Accordion title="Cannot renew token" icon="circle-question">
    * Token may not be renewable (check the Renewable column)
    * Token may have reached its explicit max TTL
    * Batch tokens cannot be renewed
  </Accordion>

  <Accordion title="Lost token value" icon="circle-question">
    * Token values cannot be retrieved after creation
    * Create a new token with the same configuration
    * Revoke the lost token to prevent unauthorized use
  </Accordion>

  <Accordion title="Permission denied with valid token" icon="circle-question">
    * Check that required policies are attached
    * Verify policies grant access to the specific path
    * Token may have been revoked by another admin
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between TTL and Max TTL?">
    TTL is the initial lifetime. When renewed, the TTL resets. Max TTL is the absolute limit - the token cannot exist beyond this time regardless of renewals.
  </Accordion>

  <Accordion title="What is a periodic token?">
    A token with a `period` set. Instead of expiring, it must be renewed within each period. As long as it's renewed, it lives indefinitely. Useful for long-running services.
  </Accordion>

  <Accordion title="Should I use service or batch tokens?">
    Use service tokens for most cases. Use batch tokens only for high-throughput scenarios where you need stateless tokens and don't need renewal or child tokens.
  </Accordion>

  <Accordion title="What happens to child tokens when parent is revoked?">
    All child tokens are automatically revoked. This is called "token revocation tree" behavior.
  </Accordion>

  <Accordion title="Can I see what a token can access?">
    Check the attached policies. Each policy defines path-based permissions. Use the Policies page to review what each policy allows.
  </Accordion>

  <Accordion title="How do I rotate a token?">
    Create a new token with the same configuration, update your application to use it, then revoke the old token. There's no in-place rotation.
  </Accordion>
</AccordionGroup>