Admin REST APIs

Relevant source files

The following files were used as context for generating this wiki page:

• warpgate-admin/src/api/users.rs
• warpgate-admin/src/api/targets.rs
• warpgate-admin/src/api/roles.rs
• warpgate-admin/src/lib.rs
• warpgate-admin/src/main.rs
• warpgate-protocol-http/src/api/api_tokens.rs

The Warpgate Admin REST APIs provide a comprehensive interface for managing the bastion host's configuration, including users, targets, roles, and security policies. Built using the poem-openapi framework, these APIs facilitate programmatic administration and power the built-in web-based management interface.

The API is served under the /@warpgate/admin/api prefix and includes built-in documentation through Swagger UI. It interacts directly with the underlying SQLite database via the sea-orm ORM to persist configuration changes and manage session data.
Sources: warpgate-admin/src/lib.rs:8-14, README.md:83-85

Architecture and Implementation

The Admin API is structured into several specialized modules, each handling a specific domain of the system configuration. The implementation leverages asynchronous Rust and the Poem web framework.

API Entry Point and Security

The API is initialized in admin_api_app, which nests the various OpenAPI services and provides access to core system services like the database connection and configuration providers. Access is controlled via AnySecurityScheme, ensuring that only authorized administrators can perform modifications.
Sources: warpgate-admin/src/lib.rs:8-43, warpgate-admin/src/api/users.rs:56

Data Flow Pattern

The following diagram illustrates the typical request-response flow for an administrative action, such as creating a new user or updating a target.

Core Modules

User Management

The User API handles the lifecycle of administrative and standard user accounts. It supports listing users with search filtering, detailed retrieval, and credential policy updates.

Endpoint	Method	Description
/users	GET	List all users, supports search query parameter.
/users	POST	Create a new user with a username and optional description.
/users/:id	PUT	Update user details and credential policies.
/users/:id/roles	GET	Retrieve roles assigned to a specific user.

Sources: warpgate-admin/src/api/users.rs:53-156

Target Configuration

Targets represent the destination hosts (SSH, MySQL, Postgres, or HTTP) that users connect to through Warpgate. The API allows administrators to define connection parameters and security options for these destinations.

Role-Based Access Control (RBAC)

Roles act as the intermediary between users and targets. The Admin API manages these relationships through assignment endpoints.

• Assignments: Users are granted access to targets by being assigned to the same roles.
• Built-in Roles: The role warpgate:admin is a protected system role that cannot be deleted or modified through standard API calls to prevent lockout.
  Sources: warpgate-admin/src/api/roles.rs:136-138, warpgate-admin/src/api/targets.rs:252-255

Data Structures

API Schemas

The APIs use strongly typed Rust structures that are automatically converted to OpenAPI schemas. Key structures include:

#[derive(Object)]
struct TargetDataRequest {
    name: String,
    description: Option<String>,
    options: TargetOptions,
}

#[derive(Object)]
struct UserDataRequest {
    username: String,
    credential_policy: Option<UserRequireCredentialsPolicy>,
    description: Option<String>,
}

Sources: warpgate-admin/src/api/targets.rs:24-28, warpgate-admin/src/api/users.rs:32-36

Target Options

The options field in a target request is polymorphic, supporting different configurations based on the protocol:

• SSH: Host, port, username, and auth method (Password/PublicKey).
• HTTP: Target URL and TLS settings.
• Databases: Host, port, username, password, and TLS configuration.
  Sources: warpgate-web/src/admin/Target.svelte:145-225

API Token Management

Users can generate API tokens for programmatic access. These tokens have configurable labels and expiry dates. When a token is created, a secret is generated and returned exactly once.

Summary

The Admin REST APIs form the backbone of Warpgate's management capabilities. By providing structured endpoints for User, Role, and Target administration, the system ensures that complex security configurations can be managed reliably through both the UI and external automation. Key protections are implemented at the API level to safeguard critical system components like the warpgate:admin role and internal management targets.