eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/how-to/authentik/authentik-api-client-generation.md
Erich Blume 591d9dd958 C2(authentik-source-build): close authentik-api-client-generation 
All three derivations verified on ringtail (nixos-25.11):
- client-go: Go API client generated and formatted with gofmt
- client-ts: TypeScript fetch client generated and compiled with tsc
- api-go-vendor-hook: setup hook built successfully

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 09:22:01 -08:00

2.7 KiB
Raw Blame History

title modified tags
Generate Authentik API Clients 2026-02-28
how-to
authentik
nix

Generate Authentik API Clients

Build Go and TypeScript API client bindings from authentik's OpenAPI spec (schema.yml). These are build-time inputs for the Go server and web UI respectively.

Context

Authentik maintains a separate repo (goauthentik/client-go) with pre-generated Go client code. The nixpkgs derivation fetches this and injects it into the Go vendor directory via a setup hook (apiGoVendorHook). The TypeScript client is generated inline from schema.yml using openapi-generator-cli.

Both clients are generated from the same schema.yml OpenAPI spec in the main authentik repo.

What to Do

  1. Create a Nix derivation (client-go) that generates Go API client bindings from schema.yml using openapi-generator-cli
  2. Create a Nix derivation (client-ts) that generates TypeScript fetch client bindings from the same spec
  3. Create a setup hook (apiGoVendorHook) that replaces goauthentik.io/api/v3 in the Go vendor directory with the generated client
  4. Verify the generated code compiles (Go: go build, TypeScript: type-check with tsc)

Key Details

  • Source spec: schema.yml in the authentik repo root
  • Go client replaces vendor/goauthentik.io/api/v3/ in the server build
  • TypeScript client replaces web/node_modules/@goauthentik/api/ in the web UI build
  • The client-go-config.patch adds disallowAdditionalPropertiesIfNotPresent: false to the OpenAPI generator config — still needed as of 2025.12.4

What We Learned

  • The Go client source comes from goauthentik/client-go (separate repo), not the main authentik repo. It contains schema.yml, config.yaml, go.mod, and go.sum.
  • The TypeScript client uses the main authentik source's schema.yml and scripts/api/ts-config.yaml.
  • The apiGoVendorHook must skip itself during FOD builds (checking $outputHash) so the Go vendorHash only depends on go.sum, not generated client content.
  • Both clients build cleanly on nixos-25.11 with openapi-generator-cli 7.17.0.

Files

  • containers/authentik/client-go.nix — Go client derivation
  • containers/authentik/client-ts.nix — TypeScript client derivation
  • containers/authentik/api-go-vendor-hook.nix — Go vendor injection hook
  • containers/authentik/client-go-config.patch — OpenAPI generator config patch
  • containers/authentik/source.nix — Shared version and source fetch

Related