From be77dc910e90f462241548f78e47616ad89b9992 Mon Sep 17 00:00:00 2001 From: Marc 'risson' Schmitt Date: Tue, 31 Mar 2026 12:52:28 +0000 Subject: [PATCH] website/api: update API clients doc (#21202) --- Makefile | 2 +- website/api/clients.mdx | 161 +++++++++++++++++++++++++++++++++- website/api/clients/golang.md | 17 ---- website/api/clients/node.md | 27 ------ website/api/clients/python.md | 13 --- website/api/sidebar.mjs | 15 +--- 6 files changed, 160 insertions(+), 75 deletions(-) delete mode 100644 website/api/clients/golang.md delete mode 100644 website/api/clients/node.md delete mode 100644 website/api/clients/python.md diff --git a/Makefile b/Makefile index 5ca965eb9b..5196921a98 100644 --- a/Makefile +++ b/Makefile @@ -285,7 +285,7 @@ docs-api-build: npm run --prefix website -w api build docs-api-watch: ## Build and watch the API documentation - npm run --prefix website -w api build:api + npm run --prefix website -w api generate npm run --prefix website -w api start docs-api-clean: ## Clean generated API documentation diff --git a/website/api/clients.mdx b/website/api/clients.mdx index 6a15a8685b..bbcbce22f5 100644 --- a/website/api/clients.mdx +++ b/website/api/clients.mdx @@ -2,14 +2,167 @@ title: API Client Overview --- -import DocCardList from "@theme/DocCardList"; - These API clients are officially supported and maintained. :::info -These API clients are primarily built around creating/updating/deleting configuration objects in authentik, and in most cases can **not** be used to implemented SSO into your application. +These API clients are primarily built around creating/updating/deleting configuration objects in authentik, and in most cases **cannot** be used to implemented SSO into your application. ::: - +The API clients are generated using the [OpenAPI Generator](https://openapi-generator.tech/) and the [OpenAPI v3 schema](https://api.goauthentik.io/schema.yml). + +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + +## Installation + + + + ```shell + go get goauthentik.io/api/v3 + ``` + + + + ```shell + pip install authentik-client + ``` + + + + ```shell + cargo install authentik-client + ``` + + + + ```shell + npm install @goauthentik/api + ``` + + + + +## Get started + + + + ```go + import ( + "context" + "goauthentik.io/api/v3" + ) + + apiConfig := api.NewConfiguration() + apiConfig.Host = "authentik.company" + apiConfig.Servers = api.ServerConfigurations{ + { + URL: "/api/v3", + }, + } + + apiClient := api.NewAPIClient(apiConfig) + + status, _, err := apiClient.AdminAPI.AdminSystemRetrieve(context.Background()).Execute() + ``` + + + + ```python + import authentik_client + + configuration = authentik_client.Configuration(host="authentik.company/api/v3") + + with authentik_client.ApiClient(configuration) as api_client: + admin_api = authentik_client.AdminApi(api_client) + + status = admin_api.admin_system_retrieve() + ``` + + + + ```rust + use authentik_client::api::{ + admin_api::admin_system_retrieve, + configuration::Configuration, + }; + + let config = Configuration { + base_path: String::from("authentik.company/api/v3"), + ..Default::default() + }; + + let status = admin_system_retrieve(&config).await?; + ``` + + + + ```ts + import { AdminApi, Configuration } from "@goauthentik/api"; + + const config = new Configuration({ + basePath: "authentik.company/api/v3", + }); + + const status = await new AdminApi(DEFAULT_CONFIG).adminSystemRetrieve(); + ``` + + + + +## Inspecting the client source code + +Each API client is published in its own repository: + + + + [Go to repository](https://github.com/goauthentik/client-go) + + + [Go to repository](https://github.com/goauthentik/client-python) + + + [Go to repository](https://github.com/goauthentik/client-rust) + + + [Go to repository](https://github.com/goauthentik/client-ts) + + + +The `main` branch only contains code for generating the API client. Navigate to a specific branch or tag to see the source code of the API client for the corresponding authentik version. For unreleased versions, see the next section. + +## Generating a custom API client + +To generate a custom API client from a specific schema, follow these steps: + +1. Clone one of the repositories above for the language you need. +2. Download the OpenAPI schema from which the client will be generated and save it at the root of the repository under `schema.yml`. +3. Run `make build version=`. + +## Usage in authentik + +API clients used by authentik itself are vendored in the [authentik repository](https://github.com/goauthentik/authentik) under the `/packages/client-*` paths. + +To generate the clients in that repository, run `make gen-clients`. To generate the client for a specific language, use the following commands: + + + + ```shell + make gen-client-go + ``` + + + + ```shell + make gen-client-rust + ``` + + + + ```shell + make gen-client-ts + ``` + + + diff --git a/website/api/clients/golang.md b/website/api/clients/golang.md deleted file mode 100644 index d735714788..0000000000 --- a/website/api/clients/golang.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Go API Client -sidebar_label: Golang -description: A Golang client for the authentik API. ---- - -The [Go API client](https://pkg.go.dev/goauthentik.io/api/v3) is generated using the [OpenAPI Generator](https://openapi-generator.tech/) and the [OpenAPI v3 schema](https://api.goauthentik.io/schema.yml). - -```shell -go get goauthentik.io/api/v3 -``` - -## Building the Go Client - -The Go client is used by the Outpost to communicate with the backend authentik server. To build the go client, run `make gen-client-go`. - -The generated files are stored in `/packages/client-go` in the root of the repository. diff --git a/website/api/clients/node.md b/website/api/clients/node.md deleted file mode 100644 index e70d9c1838..0000000000 --- a/website/api/clients/node.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Node.js API Client -sidebar_label: Node.js -description: A TypeScript client for the authentik API. ---- - -The [Node.js API client](https://www.npmjs.com/package/@goauthentik/api) is generated using the [OpenAPI Generator](https://openapi-generator.tech/) and the [OpenAPI v3 schema](https://api.goauthentik.io/schema.yml). - -```shell -npm install @goauthentik/api -``` - -## Usage - -```ts -import { AdminApi, Configuration } from "@goauthentik/api"; - -const config = new Configuration({ - basePath: "authentik.company/api/v3", -}); - -const status = await new AdminApi(DEFAULT_CONFIG).adminSystemRetrieve(); -``` - -## Building the Node.js Client - -The web client is used by the web-interface and web-FlowExecutor to communicate with authentik. To build the client, run `make gen-client-ts`. diff --git a/website/api/clients/python.md b/website/api/clients/python.md deleted file mode 100644 index 4217314b7e..0000000000 --- a/website/api/clients/python.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Python API Client -sidebar_label: Python -description: A Python client for the authentik API. ---- - -The [Python API client](https://pypi.org/project/authentik-client/) is generated using the [OpenAPI Generator](https://openapi-generator.tech/) and the [OpenAPI v3 schema](https://api.goauthentik.io/schema.yml). - -```shell -pip install authentik-client -# Or -uv pip install authentik-client -``` diff --git a/website/api/sidebar.mjs b/website/api/sidebar.mjs index ec9beba107..27d06339e8 100644 --- a/website/api/sidebar.mjs +++ b/website/api/sidebar.mjs @@ -52,20 +52,9 @@ const sidebar = { }, { - type: "category", + type: "doc", label: "API Clients", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "clients", - }, - items: [ - { - type: "autogenerated", - dirName: "clients", - }, - ], + id: "clients", }, {