### Setup Command Options

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Options for the 'warpgate setup' command, allowing customization of the database connection.

```bash
--database-url <URL>    Custom database URL
```

--------------------------------

### Unattended Setup Options

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Comprehensive options for 'warpgate unattended-setup' to configure all aspects of the server during initial setup.

```bash
--database-url <URL>                Database URL
--data-path <PATH>                  Data directory path
--http-port <PORT>                  HTTP server port
--ssh-port <PORT>                   SSH server port (enables SSH)
--mysql-port <PORT>                 MySQL server port (enables MySQL)
--postgres-port <PORT>              PostgreSQL server port (enables Postgres)
--kubernetes-port <PORT>            Kubernetes server port (enables K8s)
--record-sessions                   Enable session recording
--admin-password <PASSWORD>         Initial admin password
--external-host <HOST>              External hostname
```

--------------------------------

### Start Session Recording

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Asynchronously starts recording a user session. Requires a session ID and a target.

```rust
pub async fn start_recording(
    session_id: SessionId,
    target: &Target,
) -> Result<SessionRecorder>
```

--------------------------------

### Warpgate Configuration File Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/README.md

This is an example of the Warpgate configuration file, showing global settings, user credentials, roles, and proxy target definitions.

```yaml
# Global settings
store:
  http:
    listen: "0.0.0.0:3080"
    certificate: "tls/cert.pem"
    key: "tls/key.pem"
  ssh:
    listen: "0.0.0.0:2222"
    keys: "ssh"

http:
  external_host: "warpgate.example.com"
  external_url_scheme: "https"

# Users with credentials
users:
  - id: "550e8400-e29b-41d4-a716-446655440000"
    username: "admin"
    description: "Administrator"
    credentials:
      - kind: "password"
        hash: "$argon2id$v=19$m=19456,t=2,p=1$ early"

# Access control roles
roles:
  - id: "550e8400-e29b-41d4-a716-446655440001"
    name: "developers"
    description: "Development team"
    is_default: false

# Proxy targets
targets:
  - id: "550e8400-e29b-41d4-a716-446655440002"
    name: "prod-web"
    description: "Production web server"
    kind: "ssh"
    options:
      host: "prod.example.com"
      port: 22
      username: "ubuntu"
      auth:
        kind: "publickey"

```

--------------------------------

### Example of Verifying a Password

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Shows how to use `verify_password` to authenticate a user.

```rust
if verify_password(&password, &user.password_hash) {
    // Authenticate user
}
```

--------------------------------

### Rust OpenAPI Integration Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Illustrates how to use `poem_openapi` annotations to define API endpoints and generate OpenAPI schemas. This example shows a GET endpoint for retrieving user data.

```rust
#[OpenApi]
impl UserApi {
    #[oai(path = "/users/{id}", method = "get", operation_id = "get_user")]
    async fn get_user(&self, id: Path<Uuid>) -> GetUserResponse {
        // Implementation
    }
}
```

--------------------------------

### Run KubernetesProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Starts the Kubernetes proxy server on a specified network address.

```rust
pub async fn run(self, address: ListenEndpoint) -> Result<()>
```

--------------------------------

### Get Session Details Response (200 OK)

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response for retrieving details of a specific session. It provides comprehensive information about the session.

```json
{
  "id": "uuid",
  "username": "string",
  "target": { ... },
  "started": "2024-01-15T10:30:00Z",
  "ended": "2024-01-15T11:30:00Z",
  "protocol": "SSH",
  "remote_address": "192.168.1.100:51234"
}
```

--------------------------------

### Example of Hashing a Password

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Demonstrates how to hash a password and shows the expected output format.

```rust
let hash = hash_password("mysecretpassword");
// Result: $argon2id$v=19$m=19456,t=2,p=1$...
```

--------------------------------

### Database Connection Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Demonstrates how to establish a database connection using Sea ORM. Ensure the database URL is correctly formatted.

```rust
let db = sea_orm::Database::connect("sqlite://warpgate.db").await?;
```

--------------------------------

### HTTPProtocolServer::run

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Starts the HTTP/HTTPS server, listening for incoming connections. This method blocks until the server is shut down.

```APIDOC
## HTTPProtocolServer::run

### Description
Starts the HTTP/HTTPS server, listening for incoming connections. This method blocks until the server is shut down.

### Method
`run` (implements ProtocolServer trait)

### Signature
`async fn run(self, address: ListenEndpoint) -> Result<()>`

### Parameters
#### Path Parameters
- `address` (ListenEndpoint) - Required - The endpoint to listen on.

### Behavior
1. Loads TLS certificate and key
2. Sets up Poem web framework
3. Registers admin API routes
4. Registers reverse proxy routes
5. Starts listening (blocks until shutdown)

### Example
```rust
http_server.run(ListenEndpoint {
    address: "0.0.0.0".parse()?,
    port: 3080,
}).await?;
```
```

--------------------------------

### Password Hashing Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/auth-system.md

Demonstrates how to use the hash_password function and store the resulting hash in a UserPasswordCredential.

```rust
let hash = hash_password("my_password");
let cred = UserPasswordCredential { hash: Secret::new(hash) };
```

--------------------------------

### Database Initialization Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Initializes a database connection using a provided database URL. This function is essential for setting up database access.

```rust
pub async fn init_db(database_url: &str) -> Result<DatabaseConnection>
```

--------------------------------

### Example of Using Crypto RNG

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Demonstrates how to obtain a secure RNG and generate random bytes.

```rust
use rand::RngExt;

let bytes = get_crypto_rng().random::<[u8; 32]>();
```

--------------------------------

### Example of Verifying a TOTP Code

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Demonstrates checking a user-entered TOTP code against their secret key.

```rust
if verify_totp_code(&user.totp_secret, "123456")? {
    // TOTP verified
}
```

--------------------------------

### Run HTTPProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Starts the HTTP/HTTPS server, listening on the specified address and port. This method handles TLS, sets up the web framework, registers routes, and blocks until shutdown.

```rust
http_server.run(ListenEndpoint {
    address: "0.0.0.0".parse()?,
    port: 3080,
}).await?;
```

--------------------------------

### ProtocolServer::run

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Starts a protocol server and binds it to the specified network address. The server will run until an error occurs or it is shut down.

```APIDOC
## ProtocolServer::run

### Description
Starts a protocol server and binds it to the specified network address. The server will run until an error occurs or it is shut down.

### Method
`async fn run(self, address: ListenEndpoint) -> Result<()>`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```rust
// Example usage within an implementation of ProtocolServer
// This is illustrative and not a direct API call.
// The actual call would be made by the system starting the server.
let server = SSHProtocolServer::new(...);
server.run(ListenEndpoint::new("127.0.0.1:2222")).await;
```

### Response
#### Success Response
- `Ok(())`: Server started successfully and is running.

#### Response Example
```rust
// Success is indicated by the function returning Ok(())
// or continuing to run without returning.
```

#### Error Response
- `Err`: Indicates a binding or startup error occurred.
```

--------------------------------

### Example of Generating a TOTP Secret

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Shows how to generate a TOTP secret key, which is typically used during user onboarding for setting up 2FA.

```rust
let secret = generate_totp_secret();
// Share with user for QR code enrollment
```

--------------------------------

### List Roles Response

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response for listing existing access control roles.

```json
[
  {
    "id": "uuid",
    "name": "developers",
    "description": "Development team",
    "is_default": true
  }
]
```

--------------------------------

### GET /ldap-servers

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of all configured LDAP servers.

```APIDOC
## GET /ldap-servers

### Description
List configured LDAP servers.

### Method
GET

### Endpoint
/ldap-servers

### Response
#### Success Response (200 OK)
- **id** (uuid) - Description
- **name** (string) - Description
- **description** (string) - Description
- **host** (string) - Description
- **port** (integer) - Description
- **tls_mode** (string) - Description

#### Response Example
{
  "example": "[\n  {\n    \"id\": \"uuid\",\n    \"name\": \"Company AD\",\n    \"description\": \"Active Directory\",\n    \"host\": \"ldap.example.com\",\n    \"port\": 389,\n    \"tls_mode\": \"prefer\"\n  }\n]"
}
```

--------------------------------

### ProtocolServer run Method Signature

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Signature for the run method, which starts the protocol server. It takes a ListenEndpoint and returns a Result.

```rust
async fn run(self, address: ListenEndpoint) -> Result<()>
```

--------------------------------

### Set Log Format via CLI

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Example of how to set the log format to JSON using the command-line interface.

```bash
warpgate run --log-format json
```

--------------------------------

### Example of Emitting a UserCreated Audit Event

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Demonstrates how to create and emit a UserCreated audit event. Requires context and user information to populate the event fields.

```rust
AuditEvent::UserCreated {
    user_id: user.id,
    username: user.username.clone(),
    actor_user_id: ctx.auth.user_id(),
}.emit();
```

--------------------------------

### SessionRecorder Methods

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Provides methods for managing session recordings, including starting, recording data, and finalizing the recording.

```APIDOC
## SessionRecorder

### Description
Methods for managing terminal session recordings.

### Methods

#### `start_recording`

- **Description**: Start recording a session.
- **Parameters**:
  - `session_id` (SessionId) - Required - The ID of the session to record.
  - `target` (&Target) - Required - The target for the session recording.
- **Returns**: `Result<SessionRecorder>` - A new `SessionRecorder` instance if successful.

#### `record`

- **Description**: Write data to the session recording.
- **Parameters**:
  - `data` (&[u8]) - Required - The byte slice of data to record.
- **Returns**: `Result<()>` - Ok if data was written successfully.

#### `finalize`

- **Description**: Finalize and save the recording.
- **Returns**: `Result<()>` - Ok if the recording was finalized successfully.
```

--------------------------------

### Create Ticket Request Example

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Demonstrates how to create a temporary access ticket using the `create_ticket` function. The returned ticket ID can be used as a secret for authentication.

```rust
let ticket = create_ticket(&db, user.id, target.id, 3600).await?;
// ticket.id can be used as a secret for connecting through the ticket
```

--------------------------------

### SSHProtocolServer::run

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Starts the SSH server on a specified network address and port. This method blocks until the server is shut down.

```APIDOC
## SSHProtocolServer::run

### Description
Start SSH server on specified address.

### Method
`run` (ProtocolServer trait)

### Parameters
#### Path Parameters
- `address` (ListenEndpoint) - Required - Bind address and port

### Response
#### Success Response
- `Ok(())` - Server running (blocks until shutdown)
- `Err` - Binding or server error

### Example
```rust
let ssh_server = SSHProtocolServer::new(&services).await?;
ssh_server.run(ListenEndpoint {
    address: "0.0.0.0".parse()?,
    port: 2222,
}).await?;
```
```

--------------------------------

### List Sessions Response (200 OK)

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response for listing active and historical sessions. Includes session details like ID, user, target, start/end times, protocol, and remote address.

```json
{
  "items": [
    {
      "id": "uuid",
      "username": "string",
      "target": {
        "id": "uuid",
        "name": "string"
      },
      "started": "2024-01-15T10:30:00Z",
      "ended": "2024-01-15T11:30:00Z",
      "protocol": "SSH",
      "remote_address": "192.168.1.100:51234"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}
```

--------------------------------

### List Recordings Response (200 OK)

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response for listing session recordings. Includes recording ID, session ID, size, and duration.

```json
[
  {
    "id": "uuid",
    "session_id": "uuid",
    "size_bytes": 102400,
    "duration_seconds": 3600
  }
]
```

--------------------------------

### List Tickets Response

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response for listing existing temporary access tickets.

```json
[
  {
    "id": "uuid",
    "target_id": "uuid",
    "created_by_user_id": "uuid",
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-01-15T11:00:00Z",
    "uses": 2,
    "max_uses": 5
  }
]
```

--------------------------------

### GET /recordings

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Lists available session recordings. Can be filtered by session ID or user ID.

```APIDOC
## GET /recordings

### Description
List session recordings.

### Method
GET

### Endpoint
/recordings

### Parameters
#### Query Parameters
- **session_id** (UUID) - Optional - Filter by session
- **user_id** (UUID) - Optional - Filter by user

### Response
#### Success Response (200 OK)
- **Array** of recording objects.
  - **id** (uuid)
  - **session_id** (uuid)
  - **size_bytes** (Integer)
  - **duration_seconds** (Integer)

### Response Example
```json
[
  {
    "id": "uuid",
    "session_id": "uuid",
    "size_bytes": 102400,
    "duration_seconds": 3600
  }
]
```
```

--------------------------------

### Run SSH Protocol Server

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Starts the SSH server on a specified network address. This function blocks until the server is shut down.

```rust
async fn run(self, address: ListenEndpoint) -> Result<()>
```

```rust
let ssh_server = SSHProtocolServer::new(&services).await?;
ssh_server.run(ListenEndpoint {
    address: "0.0.0.0".parse()?,
    port: 2222,
}).await?;
```

--------------------------------

### FileConfigProvider Implementation

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

An example implementation of the `ConfigProvider` trait that loads configuration from a YAML file. It includes logic for caching and reloading configuration changes.

```rust
pub struct FileConfigProvider {
    path: PathBuf,
    // ... cache/reload logic
}

impl ConfigProvider for FileConfigProvider {
    async fn get_config(&self) -> Result<WarpgateConfig> {
        // Load from YAML file
    }

    fn subscribe(&self) -> broadcast::Receiver<()> {
        // Notify on config file changes
    }
}
```

--------------------------------

### Find Records by ID, Filter, and Relations

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/database-entities.md

Shows how to retrieve records from the database. Examples include finding a single record by its ID, finding multiple records that match a filter condition, and finding a record along with its related entities.

```rust
// Find by ID
let user = User::Entity::find_by_id(user_id).one(&db).await?;

// Find with filter
let users = User::Entity::find()
    .filter(User::Column::Username.like("alice%"))
    .all(&db)
    .await?;

// Find with relations
let user_with_roles = User::Entity::find_by_id(user_id)
    .find_with_related(Role::Entity)
    .all(&db)
    .await?;
```

--------------------------------

### SSO Get Discovery Info

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Fetches the OpenID Connect discovery document from a given issuer URL.

```APIDOC
## SSO Get Discovery Info

### Description
Fetch OpenID Connect discovery document.

### Method
`get_discovery_info`

### Parameters
- `issuer_url` (*&str*) - The URL of the OpenID Connect issuer.

### Response
- `Result<DiscoveryDocument>` - A result containing the DiscoveryDocument on success, or an error on failure.
```

--------------------------------

### Create Ticket Response

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Example JSON response upon successful creation of a temporary access ticket. Includes the ticket ID and secret.

```json
{
  "id": "uuid",
  "secret": "string",
  "target_id": "uuid",
  "expires_at": "2024-01-15T11:00:00Z",
  "max_uses": 5
}
```

--------------------------------

### SSHProtocolServer Implementation of ProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Example implementation of the ProtocolServer trait for an SSH protocol server. It delegates the run logic to a helper function.

```rust
impl ProtocolServer for SSHProtocolServer {
    async fn run(self, address: ListenEndpoint) -> Result<()> {
        run_server(self.services, address).await
    }

    fn name(&self) -> &'static str {
        "SSH"
    }
}
```

--------------------------------

### Initialize KubernetesProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Initializes the Kubernetes proxy server with provided services.

```rust
pub async fn new(services: &Services) -> Result<Self>
```

--------------------------------

### AWS Get Temporary Credentials

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Gets temporary AWS credentials for target authentication. Requires AWS configuration.

```APIDOC
## AWS Get Temporary Credentials

### Description
Get temporary AWS credentials for target authentication.

### Method
`get_temporary_credentials`

### Parameters
- `config` (*AwsConfig*) - Configuration for AWS access.

### Response
- `Result<AwsCredentials>` - A result containing the AwsCredentials on success, or an error on failure.
```

--------------------------------

### Get User Response Body (200 OK)

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

This JSON object represents a successful response from the GET /users/{id} endpoint, detailing a specific user's information, including credentials and roles.

```json
{
  "id": "uuid",
  "username": "string",
  "description": "string",
  "credentials": [
    {
      "kind": "password",
      "hash": "string"
    },
    {
      "kind": "totp",
      "key": "string"
    }
  ],
  "roles": ["developers", "admins"],
  "credential_policy": {...}
}
```

--------------------------------

### PostgresProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Acts as a PostgreSQL protocol proxy, offering features such as connection proxying, authentication handling, SSL/TLS support, and IAM role integration. It can be initialized and then started on a specified address.

```APIDOC
## PostgresProtocolServer

### Description

Acts as a PostgreSQL protocol proxy, offering features such as connection proxying, authentication handling, SSL/TLS support, and IAM role integration. It can be initialized and then started on a specified address.

### Features:
- Connection proxying
- Authentication handling
- SSL/TLS support
- IAM role integration (AWS)

### Methods

#### `new`

Initialize PostgreSQL proxy.

```rust
pub async fn new(services: &Services) -> Result<Self>
```

#### `run`

Start PostgreSQL server on specified address.

```rust
pub async fn run(self, address: ListenEndpoint) -> Result<()>
```
```

--------------------------------

### Handle UserNotFound Error

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/errors.md

Demonstrates handling the `UserNotFound` error, typically returned during authentication or user lookup failures. This example shows returning an `AuthenticationError::InvalidCredentials` when a user is not found.

```rust
if let Err(WarpgateError::UserNotFound(username)) = get_user(username) {
    return Err(AuthenticationError::InvalidCredentials);
}
```

--------------------------------

### GET /ticket-requests

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of pending ticket requests.

```APIDOC
## GET /ticket-requests

### Description
List pending ticket requests.

### Method
GET

### Endpoint
/ticket-requests

### Response
#### Success Response (200 OK)
- **id** (uuid) - Unique identifier for the ticket request.
- **target_id** (uuid) - Identifier of the target resource requested.
- **requested_by_user_id** (uuid) - Identifier of the user who requested the ticket.
- **created_at** (string) - Timestamp when the request was created (ISO 8601 format).
- **status** (string) - The current status of the request (pending, approved, denied).
- **requested_duration_seconds** (integer) - The duration requested for the ticket, in seconds.

#### Response Example
```json
[
  {
    "id": "uuid",
    "target_id": "uuid",
    "requested_by_user_id": "uuid",
    "created_at": "2024-01-15T10:00:00Z",
    "status": "pending",
    "requested_duration_seconds": 3600
  }
]
```
```

--------------------------------

### GET /roles

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of all defined access control roles.

```APIDOC
## GET /roles

### Description
List access control roles.

### Method
GET

### Endpoint
/roles

### Response
#### Success Response (200 OK)
- **id** (uuid) - Unique identifier for the role.
- **name** (string) - The name of the role.
- **description** (string) - A description of the role.
- **is_default** (boolean) - Indicates if this is the default role.

#### Response Example
```json
[
  {
    "id": "uuid",
    "name": "developers",
    "description": "Development team",
    "is_default": true
  }
]
```
```

--------------------------------

### List Users Response Body (200 OK)

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

This JSON array represents a successful response from the GET /users endpoint, listing user details including their credential policies and allowed IP ranges.

```json
[
  {
    "id": "uuid",
    "username": "string",
    "description": "string",
    "credential_policy": {
      "http": ["password"],
      "ssh": ["password", "publickey"],
      "kubernetes": null,
      "mysql": null,
      "postgres": null
    },
    "rate_limit_bytes_per_second": null,
    "allowed_ip_ranges": ["10.0.0.0/8"],
    "ldap_server_id": null
  }
]
```

--------------------------------

### GET /tickets

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of all issued temporary access tickets.

```APIDOC
## GET /tickets

### Description
List issued temporary access tickets.

### Method
GET

### Endpoint
/tickets

### Response
#### Success Response (200 OK)
- **id** (uuid) - Unique identifier for the ticket.
- **target_id** (uuid) - Identifier of the target resource the ticket provides access to.
- **created_by_user_id** (uuid) - Identifier of the user who created the ticket.
- **created_at** (string) - Timestamp when the ticket was created (ISO 8601 format).
- **expires_at** (string) - Timestamp when the ticket will expire (ISO 8601 format).
- **uses** (integer) - The number of times the ticket has been used.
- **max_uses** (integer) - The maximum number of times the ticket can be used.

#### Response Example
```json
[
  {
    "id": "uuid",
    "target_id": "uuid",
    "created_by_user_id": "uuid",
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-01-15T11:00:00Z",
    "uses": 2,
    "max_uses": 5
  }
]
```
```

--------------------------------

### MySQL Target Options

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Sets up a MySQL target, including host, port, username, authentication details, and TLS configuration.

```yaml
kind: "mysql"
options:
  host: "db.example.com"
  port: 3306
  username: "app"
  auth:
    kind: "password"
    password: "secret"
  tls:
    mode: "prefer"
    verify: false
```

--------------------------------

### Get Target Details

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves the details of a specific target by its ID.

```APIDOC
## GET /targets/{id}

### Description
Get target details.

### Method
GET

### Endpoint
/targets/{id}

### Parameters
#### Path Parameters
- **id** (uuid) - Required - The ID of the target to retrieve.

### Response
#### Success Response (200 OK)
- **id** (uuid) - The unique identifier for the target.
- **name** (string) - The name of the target.
- ... (all fields as returned by GET /targets)

### Response Example
```json
{
  "id": "uuid",
  "name": "prod-web",
  "description": "Production web server",
  "kind": "ssh",
  "options": {
    "host": "prod.example.com",
    "port": 22,
    "username": "ubuntu",
    "auth": {
      "kind": "publickey"
    }
  },
  "rate_limit_bytes_per_second": null,
  "ticket_max_duration_seconds": 3600,
  "ticket_requests_disabled": false,
  "ticket_require_approval": false,
  "allow_roles": ["developers"]
}
```
```

--------------------------------

### GET /users

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of all users. Supports searching by username.

```APIDOC
## GET /users

### Description
List all users (admin only). Supports searching by username.

### Method
GET

### Endpoint
/api/users

### Query Parameters
- **search** (string) - Optional - Search by username

### Response
#### Success Response (200 OK)
- **id** (uuid) - The user's unique identifier.
- **username** (string) - The user's username.
- **description** (string) - A description of the user.
- **credential_policy** (object) - Defines allowed credential types.
- **rate_limit_bytes_per_second** (integer) - Rate limit for bytes per second.
- **allowed_ip_ranges** (array of strings) - IP address ranges allowed for the user.
- **ldap_server_id** (string) - The ID of the LDAP server if applicable.

#### Response Example
```json
[
  {
    "id": "uuid",
    "username": "string",
    "description": "string",
    "credential_policy": {
      "http": ["password"],
      "ssh": ["password", "publickey"],
      "kubernetes": null,
      "mysql": null,
      "postgres": null
    },
    "rate_limit_bytes_per_second": null,
    "allowed_ip_ranges": ["10.0.0.0/8"],
    "ldap_server_id": null
  }
]
```

### Permissions Required
None (admin)
```

--------------------------------

### Create HTTPProtocolServer Instance

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Instantiates a new HTTP protocol server using shared services. This is a synchronous operation.

```rust
let http_server = HTTPProtocolServer::new(&services);
```

--------------------------------

### Begin, Commit, and Rollback Transactions

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/database-entities.md

Demonstrates how to initiate a database transaction, perform multiple operations within it, and then commit the changes. Sea ORM supports full ACID transactions for data consistency.

```rust
let txn = db.begin().await?;

// Multiple operations in transaction
user_entity.save(&txn).await?;
role_assignment.save(&txn).await?;

txn.commit().await?;
```

--------------------------------

### Get Target Details

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieve detailed information for a specific target by its ID.

```json
{
  "id": "uuid",
  "name": "string",
  ...
}
```

--------------------------------

### Create WebSSH Client Manager

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Initializes a new `WebSshClientManager` instance. Requires access to application services.

```rust
pub fn new(services: &Services) -> Self
```

--------------------------------

### GET /users/{id}

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves the details of a specific user identified by their ID.

```APIDOC
## GET /users/{id}

### Description
Get a specific user's details.

### Method
GET

### Endpoint
/api/users/{id}

### Path Parameters
- **id** (UUID) - Required - User ID

### Response
#### Success Response (200 OK)
- **id** (uuid) - The user's unique identifier.
- **username** (string) - The user's username.
- **description** (string) - A description of the user.
- **credentials** (array of objects) - A list of the user's credentials.
  - **kind** (string) - The type of credential (e.g., "password", "totp").
  - **hash** (string) - The hash of the credential (if applicable).
  - **key** (string) - The key for the credential (if applicable).
- **roles** (array of strings) - The roles assigned to the user.
- **credential_policy** (object) - The credential policy for the user.

#### Response Example
```json
{
  "id": "uuid",
  "username": "string",
  "description": "string",
  "credentials": [
    {
      "kind": "password",
      "hash": "string"
    },
    {
      "kind": "totp",
      "key": "string"
    }
  ],
  "roles": ["developers", "admins"],
  "credential_policy": {...}
}
```

### Status Codes
- `200 OK` - User found
- `404 NOT FOUND` - User does not exist
```

--------------------------------

### GET /sessions/{id}

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves detailed information for a specific session using its ID.

```APIDOC
## GET /sessions/{id}

### Description
Get session details.

### Method
GET

### Endpoint
/sessions/{id}

### Response
#### Success Response (200 OK)
- **id** (uuid)
- **username** (string)
- **target** (object)
- **started** (string) - ISO 8601 timestamp
- **ended** (string) - ISO 8601 timestamp
- **protocol** (string)
- **remote_address** (string)

### Response Example
```json
{
  "id": "uuid",
  "username": "string",
  "target": { ... },
  "started": "2024-01-15T10:30:00Z",
  "ended": "2024-01-15T11:30:00Z",
  "protocol": "SSH",
  "remote_address": "192.168.1.100:51234"
}
```
```

--------------------------------

### Get Base Directory for Paths

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/common-utilities.md

Retrieves the base directory used for resolving relative paths.

```rust
pub fn paths_relative_to(&self) -> PathBuf
```

--------------------------------

### Create SSH Protocol Server

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Initializes a new SSH protocol server. This method handles the generation or verification of host and client SSH keys.

```rust
pub async fn new(services: &Services) -> Result<Self>
```

```rust
let ssh_server = SSHProtocolServer::new(&services).await?;
```

--------------------------------

### init_db Function

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Initializes a database connection. It takes a database URL and returns a connection or an error.

```APIDOC
## init_db Function

### Description
Initializes a database connection. It takes a database URL and returns a connection or an error.

### Function Signature
`pub async fn init_db(database_url: &str) -> Result<DatabaseConnection>`

### Parameters
#### Path Parameters
- `database_url` (string) - Required - Database URL (SQLite format)

### Return
- Ok: Database connection ready
- Err: Connection/migration error
```

--------------------------------

### GET /admin-roles

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieves a list of all administrative roles configured in the system. Each role includes detailed permissions.

```APIDOC
## GET /admin-roles

### Description
List administrative roles.

### Method
GET

### Endpoint
/admin-roles

### Response
#### Success Response (200 OK)
- **id** (uuid) - Description
- **name** (string) - Description
- **description** (string) - Description
- **targets_create** (boolean) - Description
- **targets_edit** (boolean) - Description
- **targets_delete** (boolean) - Description
- **users_create** (boolean) - Description
- **users_edit** (boolean) - Description
- **users_delete** (boolean) - Description
- **access_roles_create** (boolean) - Description
- **access_roles_edit** (boolean) - Description
- **access_roles_delete** (boolean) - Description
- **access_roles_assign** (boolean) - Description
- **sessions_view** (boolean) - Description
- **sessions_terminate** (boolean) - Description
- **recordings_view** (boolean) - Description
- **tickets_create** (boolean) - Description
- **tickets_delete** (boolean) - Description

#### Response Example
{
  "example": "[\n  {\n    \"id\": \"uuid\",\n    \"name\": \"admin\",\n    \"description\": \"Full administrator\",\n    \"targets_create\": true,\n    \"targets_edit\": true,\n    \"targets_delete\": true,\n    \"users_create\": true,\n    \"users_edit\": true,\n    \"users_delete\": true,\n    \"access_roles_create\": true,\n    \"access_roles_edit\": true,\n    \"access_roles_delete\": true,\n    \"access_roles_assign\": true,\n    \"sessions_view\": true,\n    \"sessions_terminate\": true,\n    \"recordings_view\": true,\n    \"tickets_create\": true,\n    \"tickets_delete\": true\n  }\n]"
}
```

--------------------------------

### SSHProtocolServer::new

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Creates and initializes a new SSH protocol server. It handles the generation or verification of host and client SSH keys.

```APIDOC
## SSHProtocolServer::new

### Description
Create and initialize SSH protocol server.

### Method
`new`

### Parameters
#### Path Parameters
- `services` (Services) - Required - Shared services container

### Response
#### Success Response
- `Ok` - Server initialized with SSH keys
- `Err` - Key generation or service error

### Example
```rust
let ssh_server = SSHProtocolServer::new(&services).await?;
```
```

--------------------------------

### HTTPProtocolServer::new

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Creates a new HTTP protocol server instance. This server acts as an HTTP/HTTPS reverse proxy.

```APIDOC
## HTTPProtocolServer::new

### Description
Creates a new HTTP protocol server instance. This server acts as an HTTP/HTTPS reverse proxy.

### Method
`new`

### Signature
`pub fn new(services: &Services) -> Self`

### Parameters
#### Path Parameters
- `services` (Services) - Required - Shared services

### Return
- Synchronously created server
```

--------------------------------

### Get User ID from Request Context

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Extracts the unique identifier of the authenticated user from the request context.

```rust
pub fn user_id(&self) -> Uuid
```

--------------------------------

### Get User Roles

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/auth-system.md

Retrieves all roles assigned to a specific user. Returns a vector of Role objects.

```rust
pub async fn get_user_roles(
    db: &DatabaseConnection,
    user_id: Uuid,
) -> Result<Vec<Role>>
```

--------------------------------

### POST /users

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Creates a new user with the provided username and an optional description.

```APIDOC
## POST /users

### Description
Create a new user.

### Method
POST

### Endpoint
/api/users

### Request Body
- **username** (string) - Required
- **description** (string) - Optional

### Request Example
```json
{
  "username": "string",
  "description": "string (optional)"
}
```

### Response
#### Success Response (201 CREATED)
- **id** (uuid) - The newly created user's unique identifier.
- **username** (string) - The username of the created user.
- **description** (string) - The description of the created user.
- **credential_policy** (object) - The credential policy for the user.
- **rate_limit_bytes_per_second** (integer) - The rate limit for the user.
- **allowed_ip_ranges** (array of strings) - Allowed IP ranges for the user.
- **ldap_server_id** (string) - The LDAP server ID for the user.

#### Response Example
```json
{
  "id": "uuid",
  "username": "string",
  "description": "string",
  "credential_policy": null,
  "rate_limit_bytes_per_second": null,
  "allowed_ip_ranges": null,
  "ldap_server_id": null
}
```

### Status Codes
- `201 CREATED` - User created successfully
- `400 BAD REQUEST` - Invalid username
- `409 CONFLICT` - Username already exists

### Permissions Required
`users_create`
```

--------------------------------

### ProtocolServer Trait Definition

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Defines the interface for starting and managing protocol servers. Requires implementations to be Send and Sync.

```rust
pub trait ProtocolServer: Send + Sync {
    async fn run(self, address: ListenEndpoint) -> Result<()>;
    fn name(&self) -> &'static str;
}
```

--------------------------------

### Handle Authentication Errors

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/errors.md

Demonstrates how to handle various authentication errors, including user not found and invalid credentials, returning appropriate HTTP status codes.

```rust
match authenticate_user(&user, &credential).await {
    Ok(auth_info) => process_session(auth_info),
    Err(WarpgateError::UserNotFound(name)) => {
        eprintln!("User {} not found", name);
        // Return 401 UNAUTHORIZED
    }
    Err(WarpgateError::InvalidCredentialType) => {
        eprintln!("Invalid credential");
        // Return 401 UNAUTHORIZED
    }
    Err(e) => {
        eprintln!("Auth error: {}", e);
        // Return 500 INTERNAL_SERVER_ERROR
    }
}
```

--------------------------------

### SSO Get User Info

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Retrieves user information from an SSO token. Requires SSO provider configuration.

```APIDOC
## SSO Get User Info

### Description
Get user information from token.

### Method
`get_user_info`

### Parameters
- `config` (*SsoProvider*) - Configuration for the SSO provider.
- `token` (*&SsoToken*) - The SSO token to use for retrieving user info.

### Response
- `Result<SsoUserInfo>` - A result containing the SsoUserInfo on success, or an error on failure.
```

--------------------------------

### Get Temporary AWS Credentials

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Retrieves temporary AWS credentials for target authentication. Requires AWS configuration.

```rust
pub async fn get_temporary_credentials(
    config: &AwsConfig,
) -> Result<AwsCredentials>
```

--------------------------------

### Create Target

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Creates a new target with specified configuration options. Requires `targets_create` permission.

```APIDOC
## POST /targets

### Description
Create a new target.

### Method
POST

### Endpoint
/targets

### Parameters
#### Request Body
- **name** (string) - Required - The name of the target.
- **description** (string) - Optional - A description for the target.
- **options** (object) - Required - Configuration options specific to the target kind (see Options by Kind below).
- **rate_limit_bytes_per_second** (integer) - Optional - The rate limit for data transfer in bytes per second.
- **ticket_max_duration_seconds** (integer) - Optional - The maximum duration for tickets in seconds.
- **ticket_requests_disabled** (boolean) - Optional - Whether ticket requests are disabled.
- **ticket_require_approval** (boolean) - Optional - Whether ticket requests require approval.

### Options by Kind

**SSH:**
```json
{
  "kind": "ssh",
  "host": "string",
  "port": 22,
  "username": "string",
  "auth": {
    "kind": "publickey|password|iam_role",
    "password": "string (if password)"
  },
  "jump_host": "uuid (optional)"
}
```

**HTTP:**
```json
{
  "kind": "http",
  "url": "https://...",
  "tls": {
    "mode": "disable|prefer|require",
    "verify": false
  },
  "headers": {
    "X-Custom": "value"
  }
}
```

**MySQL:**
```json
{
  "kind": "mysql",
  "host": "string",
  "port": 3306,
  "username": "string",
  "auth": {
    "kind": "password|iam_role",
    "password": "string (if password)"
  },
  "default_database_name": "string (optional)"
}
```

**PostgreSQL:**
```json
{
  "kind": "postgres",
  "host": "string",
  "port": 5432,
  "username": "string",
  "auth": {
    "kind": "password|iam_role"
  },
  "idle_timeout_seconds": 300
}
```

**Kubernetes:**
```json
{
  "kind": "kubernetes",
  "api_url": "https://...",
  "certificate": "string (PEM)",
  "private_key": "string (PEM)",
  "ca_certificate": "string (PEM, optional)"
}
```

### Permissions Required
`targets_create`

### Response
#### Success Response (201 CREATED)
- **id** (uuid) - The ID of the created target.
- **name** (string) - The name of the target.
- ... (other fields as returned by GET /targets)

### Request Example
```json
{
  "name": "new-target",
  "description": "A newly created target",
  "options": {
    "kind": "ssh",
    "host": "example.com",
    "port": 22,
    "username": "user",
    "auth": {
      "kind": "password",
      "password": "secret"
    }
  },
  "ticket_max_duration_seconds": 7200
}
```
```

--------------------------------

### Create New Target

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Create a new target with specified options. Requires `targets_create` permissions.

```json
{
  "name": "string",
  "description": "string (optional)",
  "options": { ... },
  "rate_limit_bytes_per_second": 1000000,
  "ticket_max_duration_seconds": 3600,
  "ticket_requests_disabled": false,
  "ticket_require_approval": false
}
```

--------------------------------

### PostgreSQL Target Options

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Configures a PostgreSQL target with connection details, authentication, and idle timeout settings.

```yaml
kind: "postgres"
options:
  host: "db.example.com"
  port: 5432
  username: "postgres"
  auth:
    kind: "password"
    password: "secret"
  idle_timeout_seconds: 300
```

--------------------------------

### AuthStateStore Trait

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/core-services.md

Manages authentication state for sessions in progress. It allows starting, retrieving, setting, and removing authentication states.

```APIDOC
## AuthStateStore Trait

### Description
Manages authentication state for sessions in progress. It allows starting, retrieving, setting, and removing authentication states.

### Methods
- `start(&self, session_id: SessionId) -> Result<AuthState>`: Starts a new authentication state for a given session.
- `get(&self, session_id: SessionId) -> Result<Option<AuthState>>`: Retrieves the authentication state for a given session.
- `set(&self, session_id: SessionId, state: AuthState) -> Result<()>`: Sets the authentication state for a given session.
- `remove(&self, session_id: SessionId) -> Result<()>`: Removes the authentication state for a given session.
```

--------------------------------

### Configure MySQL Server

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Define the bind address for the MySQL server. Optionally, set the advertised version presented to clients.

```yaml
store:
  mysql:
    listen: "0.0.0.0:3306"
```

--------------------------------

### Configure PostgreSQL Server

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/configuration.md

Set the bind address for the PostgreSQL server. This configuration enables the PostgreSQL protocol listener.

```yaml
store:
  postgres:
    listen: "0.0.0.0:5432"
```

--------------------------------

### List All Targets

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Retrieve a list of all configured targets. This endpoint is restricted to administrators and supports filtering via query parameters.

```json
[
  {
    "id": "uuid",
    "name": "prod-web",
    "description": "Production web server",
    "kind": "ssh",
    "options": {
      "host": "prod.example.com",
      "port": 22,
      "username": "ubuntu",
      "auth": {
        "kind": "publickey"
      }
    },
    "rate_limit_bytes_per_second": null,
    "ticket_max_duration_seconds": 3600,
    "ticket_requests_disabled": false,
    "ticket_require_approval": false,
    "allow_roles": ["developers"]
  }
]
```

--------------------------------

### GET /recordings/{id}

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/endpoints.md

Downloads a specific session recording. This endpoint uses the WebSocket protocol for binary data transfer.

```APIDOC
## GET /recordings/{id}

### Description
Download a session recording (WebSocket).

### Method
GET

### Endpoint
/recordings/{id}

### Protocol
WebSocket

### Message Format
Binary (TTY recording in JSON format)
```

--------------------------------

### KubernetesProtocolServer

Source: https://github.com/warp-tech/warpgate/blob/main/_autodocs/api-reference/protocols.md

Manages the Kubernetes API server proxy. It can be initialized with services and then run on a specified address.

```APIDOC
## KubernetesProtocolServer

### Description

Manages the Kubernetes API server proxy. It can be initialized with services and then run on a specified address.

### Methods

#### `new`

Initialize Kubernetes proxy.

```rust
pub async fn new(services: &Services) -> Result<Self>
```

#### `run`

Start proxy on specified address.

```rust
pub async fn run(self, address: ListenEndpoint) -> Result<()>
```
```