canonical: https://jentic.com/apis/defguard.net/defguard # DefGuard API Jentic publishes the only available OpenAPI specification for DefGuard API, keeping it validated and agent-ready. DefGuard is an open-source identity and access management platform built around WireGuard VPN, OpenID Connect, and YubiKey hardware tokens. The API exposes 33 endpoints across users, devices, WireGuard networks and peers, groups, OIDC clients, webhooks, and authentication, including TOTP-based MFA. It self-hosts, so the base URL is parameterised by the deployment host, and authentication uses Bearer tokens issued by the DefGuard server. ## For AI agents Manage DefGuard users, WireGuard devices and networks, groups, OIDC clients, and MFA flows on a self-hosted identity platform. ## Scope Does not handle SaaS SSO marketplaces, device MDM, or endpoint security agents - use for DefGuard user, WireGuard, OIDC, and MFA management only. ## Capabilities - Provision and revoke WireGuard device configurations attached to user accounts - Create and manage WireGuard networks with peer membership and statistics - Authenticate users and verify TOTP codes for multi-factor login flows - Manage OpenID Connect clients used to federate logins into DefGuard - Group users for role-based access and assign group membership - Register webhooks that fire on user, device, and network lifecycle events ## Use cases ### Self-Hosted VPN User Onboarding Onboard a new employee onto a self-hosted WireGuard VPN by creating a DefGuard user, adding them to the right group, and provisioning a device configuration they can import into the WireGuard client. The /user, `/user/{username}/device`, and /group endpoints together cover the full onboarding flow without external IDP dependencies. Example prompt: Create a user via POST /user, assign them to a group, then POST `/user/{username}/device` to generate a WireGuard device configuration. ### OIDC Federation for Internal Apps Use DefGuard as the OpenID Connect provider for internal applications by registering each app as an OIDC client. The `/oauth/client` endpoints let operators rotate client credentials and inspect registered apps, so internal tools can sign users in through the same identity store that issues their VPN access. Example prompt: Call POST `/oauth/client` to register a new internal app with the required redirect URIs and store the issued client credentials. ### MFA Enforcement During Login Drive a custom login UI that authenticates a user with /auth and then verifies their TOTP code with `/auth/totp/verify` before issuing a session. This gives bespoke clients full control of the login UX while still relying on DefGuard's identity store and MFA enforcement. Example prompt: POST username and password to /auth, prompt the user for their TOTP code, then POST it to `/auth/totp/verify` to complete MFA. ### Network Lifecycle Automation Treat WireGuard networks as managed resources by creating, updating, and tearing them down through the /network endpoints, and pulling `/network/{id}/stats` for capacity dashboards. This is well suited to platform teams running multiple environments per team. Example prompt: Call GET /network to list networks, then GET `/network/{id}/stats` for each and emit metrics to the monitoring pipeline. ### AI Agent Integration via Jentic An ops agent can use Jentic to onboard a new joiner into DefGuard end-to-end: create the user, assign group membership, and provision a WireGuard device. Jentic resolves the Bearer token from the vault and provides typed schemas for each step, so the agent does not need to read DefGuard documentation to chain the calls. Example prompt: Use Jentic to search for 'create a wireguard device for a defguard user', load the operation, and execute with the user and device parameters. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/auth` | Authenticate a user with username and password | | POST | `/auth/totp/verify` | Verify a TOTP code during MFA | | POST | `/user` | Create a new user | | POST | `/user/{username}/device` | Provision a WireGuard device for a user | | POST | `/network` | Create a WireGuard network | | GET | `/network/{id}/stats` | Get statistics for a WireGuard network | | POST | `/oauth/client` | Register an OpenID Connect client | ## Key resources - **Users** — Create, retrieve, update, and delete user accounts - **Devices** — Provision WireGuard device configurations per user - **Networks** — Manage WireGuard networks and view their statistics - **Groups** — Manage groups used for role-based access - **OpenID Connect** — Register and manage OIDC clients - **Authentication** — User login and TOTP-based MFA verification - **Webhooks** — Register webhooks for lifecycle events ## Why Jentic - **Setup:** Wiring the DefGuard API by hand means learning its bearer auth, pointing at your self-hosted DefGuard host, minting a token from /auth, and carrying it across the user, WireGuard, OIDC, and MFA endpoints. Through Jentic you install once, import the DefGuard API from the API Directory, store the bearer token once, and your agent calls it. - **Permission scoping:** DefGuard puts the username and network id in the URL path (`/user/{username}/device`, `/network/{id}/stats`), so a rule can pin your agent to one user or network. You choose the operations it may call, so state-changing ones like creating users or OAuth clients are included only if you add them. - **Credential handling:** Your DefGuard bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'add a wireguard device for a user', and Jentic returns the matching DefGuard operation with its full input schema so the agent fills in the parameters and calls the right endpoint without reading docs. ## Related APIs - **Okta API** — Hosted enterprise identity platform with broader SaaS-app federation than DefGuard. - **Auth0 API** — Hosted authentication platform with extensive social and enterprise connection support. - **JumpCloud API** — Directory-as-a-service covering devices, users, and zero-trust networking. - **OneLogin API** — Cloud IDP with SSO and MFA across SaaS apps. ## FAQ ### Why is there no official OpenAPI spec for DefGuard API? DefGuard does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call DefGuard API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the DefGuard API use? The DefGuard API uses HTTP Bearer token authentication. Tokens are issued by the DefGuard server you deploy and passed in the Authorization header. Through Jentic, the token is stored encrypted in the vault and never exposed to the agent. ### Can I provision a WireGuard device with the DefGuard API? Yes. POST `/user/{username}/device` creates a new WireGuard device for the named user and returns the configuration the user imports into their WireGuard client. List existing devices with GET `/user/{username}/device.` ### Does the DefGuard API support MFA? Yes. After authenticating with POST /auth, call POST `/auth/totp/verify` with the user's TOTP code to complete an MFA-protected login flow against DefGuard's built-in TOTP support. ### What is the base URL for the DefGuard API? DefGuard is self-hosted, so the base URL is your deployment host plus `/api/v1`, for example https://defguard.example.com/api/v1. The OpenAPI server entry uses {defguard-host} as a placeholder for that hostname. ### How do I onboard a new user end-to-end through Jentic? Run `pip install jentic`, then search for 'create a defguard user', load and execute POST /user, follow up by searching for 'add a wireguard device for a defguard user' to call POST `/user/{username}/device`, and Jentic chains the credentials and schemas across both calls. ### Can I limit what my agent is allowed to do with the DefGuard API? Yes. Because you run Jentic One yourself, your own rules decide which DefGuard operations and credentials the agent may use. DefGuard puts the username and network id in the URL path, as in POST `/user/{username}/device` and GET `/network/{id}/stats`, so you can pin the agent to a single user or network. You also choose which operations it can call, so state-changing ones like POST /user or POST `/oauth/client` are available only if you add them.