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

# User Manual & Usage Guide

> Comprehensive guide for using the Hexel Secret Manager API and dashboard.

Welcome to the Hexel Secret Manager! This guide will help you get started, use the API, and follow best practices for managing secrets securely.

## Table of Contents

* [Introduction](#introduction)
* [Setup](#setup)
* [Authentication](#authentication)
* [Basic Usage](#basic-usage)
  * [Creating a Secret](#creating-a-secret)
  * [Retrieving a Secret](#retrieving-a-secret)
  * [Updating a Secret](#updating-a-secret)
  * [Deleting a Secret](#deleting-a-secret)
* [Best Practices](#best-practices)
* [Troubleshooting](#troubleshooting)

## Introduction

Hexel Secret Manager provides a secure way to store, retrieve, and manage sensitive information such as API keys, credentials, and configuration secrets. It supports both user and tenant scoped secrets, role-based access, and integration with third-party services.

## Setup

1. **Register an Account:** Sign up via the Hexel Console or contact your admin for access.
2. **Obtain API Credentials:** After registration, generate an API token from your profile or admin dashboard.
3. **Install Required Tools:**
   * For API usage: Any HTTP client (e.g., curl, Postman) or SDK if available.
   * For dashboard: Use a modern web browser.

## Authentication

All API requests require a Bearer token. Include it in the `Authorization` header:

```http
Authorization: Bearer <your-access-token>
```

Tokens can be obtained via the `/api/v1/auth/login` endpoint. See the [Auth endpoints](./endpoints/auth-login) for details.

## Basic Usage

### Creating a Secret

To create a user secret:

```http
POST /api/v1/user-secrets/
Content-Type: application/json
Authorization: Bearer <token>

{
  "service_name": "my-service",
  "secret_key_name": "API_KEY",
  "secret_value": "supersecretvalue"
}
```

### Retrieving a Secret

To get a secret by ID:

```http
GET /api/v1/user-secrets/{secret_id}
Authorization: Bearer <token>
```

### Updating a Secret

To update a secret:

```http
PUT /api/v1/user-secrets/{secret_id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "secret_value": "newsecretvalue"
}
```

### Deleting a Secret

To delete a secret:

```http
DELETE /api/v1/user-secrets/{secret_id}
Authorization: Bearer <token>
```

## Best Practices

* **Rotate secrets regularly** to minimize risk.
* **Use tenant secrets** for shared resources, user secrets for personal credentials.
* **Restrict access** using roles and permissions.
* **Never share tokens** or secrets in plaintext.
* **Audit usage** via the dashboard or API logs.

## Troubleshooting

* **401 Unauthorized:** Check your token and ensure it is not expired.
* **403 Forbidden:** You may lack the required role or permission.
* **404 Not Found:** The secret or resource does not exist or you lack access.
* **Other issues:** Refer to the [API Reference](./openapi) or contact support at [support@hexelstudio.com](mailto:support@hexelstudio.com).

For more advanced scenarios, see the endpoint-specific documentation in the sidebar.