Zitadel Go SDK

https://github.com/zitadel/zitadel-go
Admin
Zitadel Go SDK is a comprehensive library that provides convenient and idiomatic Go bindings for...
Tokens:26,958
Snippets:333
Trust Score:9.5
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Zitadel Go SDK

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/overview.md

Use the go get command to add the SDK to your project dependencies.

```bash
go get -u github.com/zitadel/zitadel-go/v3
```

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

### Initialize Authenticator

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Example of setting up a new Authenticator instance for a web application.

```go
package main

import (
	"context"
	"log"
	"github.com/zitadel/zitadel-go/v3/pkg/authentication"
	"github.com/zitadel/zitadel-go/v3/pkg/authentication/oidc"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	z := zitadel.New("example.zitadel.cloud")
	ctx := context.Background()
	
	authHandler := oidc.DefaultAuthentication(
		"client-id",
		"http://localhost:8080/auth/callback",
		"encryption-key-must-be-32-chars-long!!!",
	)
	
	authenticator, err := authentication.New(
		ctx,
		z,
		"encryption-key-must-be-32-chars-long!!!",
		authHandler,
	)
	if err != nil {
		log.Fatal(err)
	}
	
	// Use authenticator in HTTP handlers
}
```

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

### Initialize Zitadel Client

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Examples for basic client initialization and authentication using a JWT profile.

```go
package main

import (
	"context"
	"log"
	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	ctx := context.Background()
	z := zitadel.New("example.zitadel.cloud")
	
	c, err := client.New(ctx, z)
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	
	// Access services via c.ManagementService(), c.UserServiceV2(), etc.
}
```

```go
package main

import (
	"context"
	"log"
	"github.com/zitadel/oidc/v3/pkg/oidc"
	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	ctx := context.Background()
	z := zitadel.New("example.zitadel.cloud")
	
	authOption := client.DefaultServiceUserAuthentication(
		"path/to/key.json",
		oidc.ScopeOpenID,
		client.ScopeZitadelAPI(),
	)
	
	c, err := client.New(ctx, z, client.WithAuth(authOption))
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
}
```

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

### Configure ZITADEL for Web Applications

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Setup authentication for browser-based applications using OIDC and secure cookie handling.

```go
// Configuration
domain := "https://example.zitadel.cloud"
clientID := "client-id"
redirectURI := "https://myapp.com/auth/callback"
encryptionKey := os.Getenv("ENCRYPTION_KEY")

z := zitadel.New(domain)

authHandler := oidc.DefaultAuthentication(clientID, redirectURI, encryptionKey)

authenticator, _ := authentication.New(
	ctx, z, encryptionKey, authHandler,
	authentication.WithExternalSecure(true), // Behind HTTPS proxy
	authentication.WithPostLogoutRedirectURI("https://myapp.com"),
)

// Mount at /auth/
http.Handle("/auth/", authenticator)
```

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

### Webhook Integration Example

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-actions.md

A complete Go implementation of an HTTP webhook receiver that validates ZITADEL signatures before processing the payload.

```go
package main

import (
	"encoding/json"
	"io"
	"log"
	"net/http"
	"github.com/zitadel/zitadel-go/v3/pkg/actions"
)

type WebhookPayload struct {
	ID        string                 `json:"id"`
	EventType string                 `json:"type"`
	CreatedAt string                 `json:"createdAt"`
	Data      map[string]interface{} `json:"data"`
}

func webhookHandler(signingKey string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// Read payload
		payload, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "Failed to read body", http.StatusBadRequest)
			return
		}
		defer r.Body.Close()

		// Validate signature
		err = actions.ValidateRequestPayload(payload, &r.Header, signingKey)
		if err != nil {
			log.Printf("Signature validation failed: %v", err)
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}

		// Parse webhook
		var event WebhookPayload
		err = json.Unmarshal(payload, &event)
		if err != nil {
			http.Error(w, "Failed to parse payload", http.StatusBadRequest)
			return
		}

		// Process event
		log.Printf("Received event: %s (ID: %s)", event.EventType, event.ID)
		
		// Example: handle user.created event
		if event.EventType == "user.created" {
			log.Printf("New user created: %v", event.Data)
		}

		w.WriteHeader(http.StatusOK)
		w.Write([]byte("Event processed"))
	}
}

func main() {
	signingKey := "my-zitadel-webhook-signing-key"
	
	http.HandleFunc("/webhook/zitadel", webhookHandler(signingKey))
	
	log.Println("Starting webhook receiver on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

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

### Example Invalid Tokens

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/errors.md

Examples of authorization headers that trigger ErrMissingToken.

```text
Authorization: Bearer          // Missing token after Bearer
Authorization: bearer xyz      // Wrong case (must be "Bearer ")
Authorization: xyz             // Missing "Bearer " prefix
Authorization:                 // Empty
```

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

### ValidatePayloadWithTolerance Usage Example

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-actions.md

Demonstrates how to use ValidatePayloadWithTolerance within an HTTP handler to verify ZITADEL webhook signatures.

```go
package main

import (
	"io"
	"log"
	"net/http"
	"time"
	"github.com/zitadel/zitadel-go/v3/pkg/actions"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	payload, _ := io.ReadAll(r.Body)
	sigHeader := r.Header.Get("ZITADEL-Signature")
	
	// Accept signatures up to 1 hour old
	err := actions.ValidatePayloadWithTolerance(
		payload,
		sigHeader,
		"my-signing-key",
		time.Hour,
	)
	if err != nil {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}
	
	w.WriteHeader(http.StatusOK)
}

func main() {
	http.HandleFunc("/webhook", webhookHandler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

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

### Get Authorization Token

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Retrieves the currently stored authorization token.

```go
func (c *IntrospectionContext) GetToken() string
```

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

### func (a *Authenticator[T]) Authenticate

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Starts a new OIDC authentication flow by redirecting to the login UI.

```APIDOC
## func (a *Authenticator[T]) Authenticate

### Description
Starts a new OIDC authentication by redirecting to the login UI. The state parameter is encrypted and stored in the redirect.

### Parameters
- **w** (http.ResponseWriter) - Required - HTTP response writer
- **r** (*http.Request) - Required - HTTP request
- **requestedURI** (string) - Required - Original URI to redirect to after login
```

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

### Initialize a new Zitadel client

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/00-START-HERE.md

Demonstrates the function signature and basic instantiation of the Zitadel client.

```go
// 1. Find the function signature
func New(ctx context.Context, zitadel *zitadel.Zitadel, opts ...Option) (*Client, error)

// 2. Check parameters table for types/defaults
// 3. Copy example code

c, err := client.New(ctx, z, client.WithAuth(authOption))
if err != nil {
    log.Fatal(err)
}
```

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

### Initialize ZITADEL Client with Environment Variables

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Load configuration from environment variables to initialize the ZITADEL client.

```go
package main

import (
	"os"
	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	domain := os.Getenv("ZITADEL_DOMAIN")
	keyPath := os.Getenv("ZITADEL_KEY_PATH")
	encryptionKey := os.Getenv("ENCRYPTION_KEY")
	
	z := zitadel.New(domain)
	
	authOpt := client.DefaultServiceUserAuthentication(keyPath)
	// ...
}
```

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

### Initialize Zitadel Configuration

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Use the New constructor to create a configuration instance with optional settings.

```go
z := zitadel.New("example.zitadel.cloud")
// Uses: https://example.zitadel.cloud:443
```

```go
z := zitadel.New(
	"localhost",
	zitadel.WithInsecure("8080"),
	zitadel.WithTransportHeader("Proxy-Authorization", "Bearer proxy-token"),
)
// Uses: http://localhost:8080
```

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

### Initialize Zitadel Instance

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Configure the Zitadel instance connection using the zitadel.New constructor and functional options.

```go
z := zitadel.New(
	"example.zitadel.cloud",
	zitadel.WithPort(9443),
	zitadel.WithInsecureSkipVerifyTLS(),
	zitadel.WithTransportHeader("Proxy-Authorization", "Bearer token"),
)
```

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

### Load Key Files

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Load service account configurations from a file path or raw byte data.

```go
// From file path
keyFile, err := client.ConfigFromKeyFile("path/to/key.json")

// From raw bytes
data := []byte(`{"type":"serviceaccount",...}`)
keyFile, err := client.ConfigFromKeyFileData(data)
```

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

### Load configuration from key file

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Reads and parses a key.json file from the specified disk path.

```go
keyFile, err := client.ConfigFromKeyFileData(data)
keyFile, err := client.ConfigFromKeyFile("path/to/key.json")
if err != nil {
	log.Fatal(err)
}
```

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

### Generate ZITADEL API Scope

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates a scope string for general ZITADEL API access, often used during service user authentication setup.

```go
scope := client.ScopeZitadelAPI()
authOption := client.DefaultServiceUserAuthentication("key.json", oidc.ScopeOpenID, scope)
```

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

### zitadel.New

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Initializes a new Zitadel instance configuration.

```APIDOC
## zitadel.New(domain string, opts ...Option)

### Description
Creates a new Zitadel instance configuration object used to connect to the Zitadel API.

### Parameters
- **domain** (string) - Required - The domain name of the Zitadel instance (e.g., example.zitadel.cloud).
- **opts** (...Option) - Optional - Configuration options such as WithPort, WithInsecureSkipVerifyTLS, or WithTransportHeader.
```

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

### func New

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Initializes a new Zitadel client with the provided context, configuration, and optional settings.

```APIDOC
## func New

### Description
Initializes a new Zitadel client. This client is used to access various Zitadel services.

### Signature
`func New(ctx context.Context, zitadel *zitadel.Zitadel, opts ...Option) (*Client, error)`

### Parameters
- **ctx** (context.Context) - Required - Context for initialization
- **zitadel** (*zitadel.Zitadel) - Required - Zitadel instance configuration
- **opts** (...Option) - Optional - Optional configuration options

### Returns
- `(*Client, error)` - Initialized client or error if connection fails
```

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

### client.New

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Initializes a new gRPC client for interacting with the Zitadel API.

```APIDOC
## client.New(ctx context.Context, z *zitadel.Zitadel, opts ...Option)

### Description
Creates a new gRPC client instance using the provided Zitadel configuration and client options.

### Parameters
- **ctx** (context.Context) - Required - The context for the client connection.
- **z** (*zitadel.Zitadel) - Required - The Zitadel instance configuration.
- **opts** (...Option) - Optional - Client options including authentication (WithAuth) or gRPC dial options (WithGRPCDialOptions).
```

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

### Initialize JWT Profile Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using a pre-loaded key file.

```go
keyFile, err := client.ConfigFromKeyFile("path/to/key.json")
if err != nil {
	log.Fatal(err)
}
authOption := client.AuthenticationJWTProfile(keyFile, oidc.ScopeOpenID)
```

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

### client.ConfigFromKeyFile

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Loads service account configuration from a JSON key file.

```APIDOC
## client.ConfigFromKeyFile(path string)

### Description
Reads and parses a Zitadel-generated key.json file from the filesystem to be used for authentication.

### Parameters
- **path** (string) - Required - The file path to the key.json file.
```

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

### Access System Service

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the System configuration API.

```go
func (c *Client) SystemService() system.SystemServiceClient
```

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

### Initialize Authenticator

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Configure the web app authenticator using authentication.Option to define OIDC settings, session management, and hooks.

```go
authenticator, err := authentication.New(
	ctx,
	z,
	"encryption-key-32-chars-or-more!",
	oidc.DefaultAuthentication(
		"client-id",
		"http://localhost:8080/auth/callback",
		"encryption-key-32-chars-or-more!",
	),
	authentication.WithLogger(logger),
	authentication.WithSessionCookieName("my_app_session"),
	authentication.WithExternalSecure(true),
	authentication.WithPostLogoutRedirectURI("http://localhost:8080/goodbye"),
	authentication.WithOnAuthenticated(func(ctx context.Context, authCtx authentication.Ctx) error {
		// Custom post-auth hook
		return nil
	}),
	authentication.WithSessionStore(customStore),
	authentication.WithCookieSession(),
)
```

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

### Access Instance Service V2

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the Instance API v2.

```go
func (c *Client) InstanceServiceV2() instanceV2.InstanceServiceClient
```

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

### Configure Client Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Set up authentication for the gRPC client using service user credentials.

```go
authOpt := client.DefaultServiceUserAuthentication(
	"path/to/key.json",
	oidc.ScopeOpenID,
	client.ScopeZitadelAPI(),
)

c, err := client.New(ctx, z, client.WithAuth(authOpt))
```

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

### Initialize Service User Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using a JWT Profile key file with automatic file reading.

```go
authOption := client.DefaultServiceUserAuthentication(
	"path/to/key.json",
	oidc.ScopeOpenID,
	client.ScopeZitadelAPI(),
)
c, err := client.New(ctx, z, client.WithAuth(authOption))
```

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

### Implement Login Handler

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Using the Authenticate method to initiate the OIDC flow.

```go
func loginHandler(w http.ResponseWriter, r *http.Request) {
	authenticator.Authenticate(w, r, "/")
}
```

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

### PAT

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using a Personal Access Token.

```APIDOC
## func PAT(pat string) TokenSourceInitializer

### Description
Creates an authentication initializer using a Personal Access Token.

### Parameters
- **pat** (string) - Required - Personal access token

### Returns
- **TokenSourceInitializer** - Token source initializer

### Example
```go
authOption := client.PAT("my-personal-access-token")
c, err := client.New(ctx, z, client.WithAuth(authOption))
```
```

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

### Client Constructor Definition

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

The signature for creating a new Zitadel client instance.

```go
func New(ctx context.Context, zitadel *zitadel.Zitadel, opts ...Option) (*Client, error)
```

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

### InstanceServiceV2

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the Instance API v2.

```APIDOC
## func (c *Client) InstanceServiceV2()

### Description
Returns the client for the Instance API v2.

### Returns
- **instanceV2.InstanceServiceClient** - Client for Instance API v2
```

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

### Key Rotation Pattern

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-actions.md

Demonstrates how to compute headers with multiple keys and validate payloads against multiple potential keys.

```go
// Compute header with multiple keys (old and new)
header := actions.ComputeSignatureHeader(
	time.Now(),
	payload,
	"old-key",
	"new-key",
)
// Produces: t=1234567890,v1=signature-with-old-key,v1=signature-with-new-key
```

```go
// Try validation with old key first, then new key
err := actions.ValidatePayload(payload, sigHeader, "old-key")
if err != nil {
	err = actions.ValidatePayload(payload, sigHeader, "new-key")
	if err != nil {
		// Both keys failed
		return err
	}
}
// One of the keys was valid
```

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

### Initialize Default OIDC Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Creates an OIDC handler with PKCE and default scopes. The encryption key must be at least 32 bytes long.

```go
authHandler := oidc.DefaultAuthentication(
	"client-id",
	"http://localhost:8080/auth/callback",
	"encryption-key-must-be-at-least-32-bytes-long!!!",
	oidc.ScopeOpenID,
	oidc.ScopeProfile,
)
```

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

### Configure ZITADEL for Service-to-Service API

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Authenticate service users using a key file for machine-to-machine communication.

```go
// Configuration
z := zitadel.New("example.zitadel.cloud")

authOpt := client.DefaultServiceUserAuthentication(
	"./config/key.json",
	oidc.ScopeOpenID,
	client.ScopeZitadelAPI(),
)

apiClient, _ := client.New(ctx, z, client.WithAuth(authOpt))

// Make API calls
resp, _ := apiClient.UserServiceV2().ListUsers(ctx, &userV2.ListUsersRequest{})
```

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

### Initialize Pre-Signed JWT Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using a pre-signed JWT token.

```go
authOption := client.PreSignedJWT("eyJhbGc...")
c, err := client.New(ctx, z, client.WithAuth(authOption))
```

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

### func New

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Creates a new Zitadel configuration instance for the specified domain with optional configuration settings.

```APIDOC
## func New(domain string, options ...Option) *Zitadel

### Description
Creates a Zitadel configuration for the specified domain.

### Parameters
- **domain** (string) - Required - Domain of the Zitadel instance (e.g., example.zitadel.cloud)
- **options** (...Option) - Optional - Optional configuration options

### Returns
- ***Zitadel** - Configured Zitadel instance
```

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

### File Size Distribution Table

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/MANIFEST.md

A summary of the documentation file sizes and line counts.

```text
api-reference-client.md       747 lines / 16 KB
api-reference-authorization.md 727 lines / 16 KB
api-reference-authentication.md 671 lines / 16 KB
configuration.md              508 lines / 12 KB
errors.md                      517 lines / 12 KB
INDEX.md                       400 lines / 12 KB
api-reference-actions.md       412 lines / 9.6 KB
types.md                       412 lines / 9.7 KB
api-reference-zitadel.md       274 lines / 5.5 KB
README.md                      224 lines / 5.7 KB
overview.md                     65 lines / 2.4 KB
─────────────────────────────────────────────
Total                        4957 lines / 132 KB
```

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

### SystemService

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the System API.

```APIDOC
## func (c *Client) SystemService()

### Description
Returns the client for the System API (system configuration).

### Returns
- **system.SystemServiceClient** - Client for System API
```

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

### Zitadel Instance Methods

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Methods to retrieve configuration details from a configured Zitadel instance.

```APIDOC
## Method: func (z *Zitadel) Origin() string
Returns the HTTP origin string (schema://hostname[:port]) without path component.

## Method: func (z *Zitadel) Host() string
Returns the host string (domain:port) without schema.

## Method: func (z *Zitadel) IsTLS() bool
Returns whether TLS is enabled.

## Method: func (z *Zitadel) IsInsecureSkipVerifyTLS() bool
Returns whether TLS certificate verification is skipped.

## Method: func (z *Zitadel) Domain() string
Returns the domain of the Zitadel instance.

## Method: func (z *Zitadel) TransportHeaders() map[string]string
Returns custom transport headers to be sent with all requests.
```

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

### Retrieve Host Address

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Returns the domain and port of the configured instance.

```go
z := zitadel.New("example.zitadel.cloud")
fmt.Println(z.Host()) // Output: example.zitadel.cloud:443
```

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

### ConfigFromKeyFile

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Reads and parses a key.json file from the specified file path.

```APIDOC
## func ConfigFromKeyFile(path string) (*KeyFile, error)

### Description
Reads and parses a key.json file from disk.

### Parameters
- **path** (string) - Required - File path to key.json

### Returns
- **(*KeyFile, error)** - Parsed key file or error

### Example
```go
keyFile, err := client.ConfigFromKeyFile("path/to/key.json")
if err != nil {
	log.Fatal(err)
}
```
```

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

### Configure OIDC Authorization Code Flow

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Initializes an OIDC handler using the Authorization Code Flow with PKCE authentication.

```go
authHandler := oidc.WithCodeFlow(
	oidc.PKCEAuthentication(
		"client-id",
		"http://localhost:8080/auth/callback",
		[]string{oidc.ScopeOpenID},
		httphelper.NewCookieHandler([]byte(key), []byte(key)),
	),
)
```

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

### Initialize Password Authentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using OAuth2 Client Credentials Grant.

```go
authOption := client.PasswordAuthentication(
	"client-id",
	"client-secret",
	oidc.ScopeOpenID,
	client.ScopeZitadelAPI(),
)
c, err := client.New(ctx, z, client.WithAuth(authOption))
```

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

### Configure Client Authentication with PAT

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Sets the authentication mechanism using a Personal Access Token.

```go
authOption := client.PAT("my-personal-access-token")
c, err := client.New(ctx, z, client.WithAuth(authOption))
```

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

### Configure TLS Certificate Verification

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Manage TLS settings for production, development, or custom CA requirements.

```go
// Uses system certificate pool
z := zitadel.New("example.zitadel.cloud")
// No additional config needed
```

```go
// Skip certificate verification (development only)
z := zitadel.New(
	"internal.zitadel.cloud",
	zitadel.WithInsecureSkipVerifyTLS(),
)
```

```go
// For custom CA certificates, use WithGRPCDialOptions
import "crypto/tls"
import "google.golang.org/grpc/credentials"

opts := []grpc.DialOption{
	grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
		RootCAs: customCertPool,
	})),
}

c, err := client.New(ctx, z, client.WithGRPCDialOptions(opts...))
```

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

### Implement Web App Authentication Middleware

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/INDEX.md

Redirects unauthenticated users to the login page using the authentication package.

```go
func authRequired(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !authentication.IsAuthenticated(r.Context()) {
			http.Redirect(w, r, "/login", http.StatusFound)
			return
		}
		next.ServeHTTP(w, r)
	})
}
```

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

### Parse configuration from byte data

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Parses raw key.json data provided as a byte slice.

```go
data := []byte(`{"type":"serviceaccount",...}`)
keyFile, err := client.ConfigFromKeyFileData(data)
```

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

### Define and Handle ErrNotSigned

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/errors.md

Error returned when the ZITADEL-Signature header is missing from the request.

```go
var ErrNotSigned = errors.New("webhook has no Zitadel-Signature header")
```

```go
err := actions.ValidatePayload(payload, sigHeader, signingKey)
if err == actions.ErrNotSigned {
	log.Println("Webhook missing signature header")
	http.Error(w, "Unauthorized", http.StatusUnauthorized)
	return
}
```

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

### Retrieve Origin URL

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Returns the full HTTP origin string including schema and port.

```go
z := zitadel.New("example.zitadel.cloud")
fmt.Println(z.Origin()) // Output: https://example.zitadel.cloud

z := zitadel.New("localhost", zitadel.WithInsecure("8080"))
fmt.Println(z.Origin()) // Output: http://localhost:8080
```

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

### Authenticate with Client Credentials in Go

Source: https://github.com/zitadel/zitadel-go/blob/main/README.md

Uses client ID and secret for server-to-server communication in trusted environments.

```go
package main

import (
	"context"
	"log"
	"os"
	"log/slog"

	"github.com/zitadel/oidc/v3/pkg/oidc"

	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	domain := "https://example.us1.zitadel.cloud"
	clientID := "id"
	clientSecret := "secret"

	ctx := context.Background()

	authOption := client.PasswordAuthentication(
		clientID,
		clientSecret,
		oidc.ScopeOpenID,
		client.ScopeZitadelAPI(),
	)

	api, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))
	if err != nil {
		slog.Error("could not create api client", "error", err)
		os.Exit(1)
	}

	resp, err := api.ManagementService().GetMyOrg(ctx, &management.GetMyOrgRequest{})
	if err != nil {
		slog.Error("gRPC call failed", "error", err)
		os.Exit(1)
	}

	log.Printf("Successfully called API: Your organization is %s", resp.GetOrg().GetName())
}
```

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

### Configure ZITADEL for Protected REST API

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Implement middleware to verify authorization tokens for REST API endpoints.

```go
// Configuration
z := zitadel.New("example.zitadel.cloud")

verifier := oauth.DefaultAuthorization("./config/key.json")

authorizer, _ := authorization.New(ctx, z, verifier)

// Middleware
func requireAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		token := r.Header.Get("Authorization")
		
		authCtx, err := authorizer.CheckAuthorization(r.Context(), token)
		if err != nil {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}
		
		ctx := authorization.WithAuthContext(r.Context(), authCtx)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}
```

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

### Define KeyFile structure

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Represents the structure of a Zitadel key.json file.

```go
type KeyFile struct {
	Type     KeyType // ServiceAccountKey or ApplicationKey
	KeyID    string  // Key identifier
	Key      []byte  // Private key material (PEM-encoded)
	UserID   string  // For service accounts
	ClientID string  // For applications
	AppID    string  // For applications
}
```

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

### Configure In-Memory Session Storage

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Use the default in-memory session storage, which is suitable for single-instance deployments but loses data on restart.

```go
// Sessions stored in application memory
// Lost on restart
// Good for single-instance deployments
sessions := authentication.NewInMemorySessions[*UserContext]()
```

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

### Configure slog logging for ZITADEL

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Integrate Go's standard library slog with ZITADEL authentication and authorization components.

```go
import "log/slog"

logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
	Level: slog.LevelDebug,
}))

authenticator, err := authentication.New(
	ctx, z, key, handler,
	authentication.WithLogger(logger),
)

authorizer, err := authorization.New(
	ctx, z, verifier,
	authorization.WithLogger(logger),
)
```

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

### Initialize Authorizer

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Constructor for creating an Authorizer instance with OAuth2 introspection.

```go
func New[T Ctx](ctx context.Context, zitadel *zitadel.Zitadel, initVerifier VerifierInitializer[T], options ...Option[T]) (*Authorizer[T], error)
```

```go
package main

import (
	"context"
	"log"
	"github.com/zitadel/zitadel-go/v3/pkg/authorization"
	"github.com/zitadel/zitadel-go/v3/pkg/authorization/oauth"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	z := zitadel.New("example.zitadel.cloud")
	ctx := context.Background()
	
	verifier := oauth.DefaultAuthorization("path/to/key.json")
	
	authorizer, err := authorization.New(
		ctx,
		z,
		verifier,
	)
	if err != nil {
		log.Fatal(err)
	}
	
	// Use authorizer to check tokens
}
```

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

### Add Authentication Context

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Injects an authentication context into a base context.Context.

```go
newCtx := authentication.WithAuthContext(r.Context(), authCtx)
```

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

### Access SAML Service V2

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the SAML API v2.

```go
func (c *Client) SAMLServiceV2() samlV2.SAMLServiceClient
```

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

### Implement Custom Session Store

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Define a custom session store by implementing the Sessions[T] interface and passing it to the authenticator.

```go
type Sessions[T authentication.Ctx] interface {
	Get(sessionID string) (T, error)
	Set(sessionID string, authCtx T) error
	Delete(sessionID string) error
}

// Example: Redis-backed sessions
authenticator, err := authentication.New(
	ctx, z, key, handler,
	authentication.WithSessionStore(redisSessionStore),
)
```

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

### Define Zitadel Configuration Struct

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

The Zitadel struct holds connection parameters including domain, port, and TLS settings.

```go
type Zitadel struct {
	domain                string            // Domain of the Zitadel instance
	port                  string            // Port (default "443")
	tls                   bool              // Use TLS (default true)
	insecureSkipVerifyTLS bool              // Skip TLS verification (default false)
	transportHeaders      map[string]string // Custom HTTP headers
}
```

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

### Configure Authorizer with Logger

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Sets a custom logger for the authorizer using the WithLogger option.

```go
func WithLogger[T Ctx](logger *slog.Logger) Option[T]
```

```go
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
authorizer, err := authorization.New(
	ctx, z, verifier,
	authorization.WithLogger(logger),
)
```

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

### Configure insecure connection

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-zitadel.md

Disables TLS and sets a specific port. Do not use in production environments.

```go
z := zitadel.New("localhost", zitadel.WithInsecure("8080"))
// Connects to: http://localhost:8080
```

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

### Set Custom Session Store

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Provides a custom implementation for session storage.

```go
func WithSessionStore[T Ctx](sessions Sessions[T]) Option[T]
```

```go
customStore := NewRedisSessionStore()
authenticator, err := authentication.New(
	ctx, z, key, authHandler,
	authentication.WithSessionStore(customStore),
)
```

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

### Zitadel Key File Format

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

The expected JSON structure for Zitadel-generated service account key files.

```json
{
	"type": "serviceaccount",
	"keyId": "123456789",
	"key": "-----BEGIN RSA PRIVATE KEY-----\n...",
	"userId": "user-id-123"
}
```

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

### Configure gRPC Dial Options

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/configuration.md

Pass custom gRPC dial options to the client constructor.

```go
opts := []grpc.DialOption{
	grpc.WithDefaultCallOptions(
		grpc.MaxCallRecvMsgSize(50 * 1024 * 1024),
	),
}

c, err := client.New(ctx, z, client.WithGRPCDialOptions(opts...))
```

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

### Service Access Methods

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Methods available on the Client instance to access specific Zitadel service clients.

```go
func (c *Client) ManagementService() management.ManagementServiceClient
```

```go
func (c *Client) UserServiceV2() userV2.UserServiceClient
```

```go
func (c *Client) AdminService() admin.AdminServiceClient
```

```go
func (c *Client) AuthService() auth.AuthServiceClient
```

```go
func (c *Client) AuthorizationServiceV2() authorizationV2.AuthorizationServiceClient
```

```go
func (c *Client) OrganizationServiceV2() orgV2.OrganizationServiceClient
```

```go
func (c *Client) ProjectServiceV2() projectV2.ProjectServiceClient
```

```go
func (c *Client) SessionServiceV2() sessionV2.SessionServiceClient
```

```go
func (c *Client) OIDCServiceV2() oidcV2.OIDCServiceClient
```

```go
func (c *Client) ActionServiceV2() actionV2.ActionServiceClient
```

```go
func (c *Client) ApplicationServiceV2() applicationV2.ApplicationServiceClient
```

```go
func (c *Client) FeatureServiceV2() featureV2.FeatureServiceClient
```

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

### Define HandlerInitializer function type

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/types.md

Signature for functions that initialize an authentication handler.

```go
type HandlerInitializer[T Ctx] func(ctx context.Context, zitadel *zitadel.Zitadel) (Handler[T], error)
```

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

### AuthenticationJWTProfile

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using JWT Profile Grant with a pre-loaded key file.

```APIDOC
## func AuthenticationJWTProfile(file *KeyFile, scopes ...string) TokenSourceInitializer

### Description
Creates an authentication initializer using JWT Profile Grant with a pre-loaded key file.

### Parameters
- **file** (*KeyFile) - Required - Parsed key file
- **scopes** (...string) - Optional - OAuth2 scopes

### Returns
- **TokenSourceInitializer** - Token source initializer

### Example
```go
keyFile, err := client.ConfigFromKeyFile("path/to/key.json")
if err != nil {
	log.Fatal(err)
}
authOption := client.AuthenticationJWTProfile(keyFile, oidc.ScopeOpenID)
```
```

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

### Verify session with IsAuthenticated

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Checks for an existing session using the provided HTTP request. Returns an authentication context or an error if the session is invalid or missing.

```go
func (a *Authenticator[T]) IsAuthenticated(req *http.Request) (T, error)
```

```go
authCtx, err := authenticator.IsAuthenticated(r)
if err != nil {
	// Not authenticated
	http.Redirect(w, r, "/login", http.StatusFound)
	return
}
// User is authenticated, authCtx contains user info
```

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

### Initialize Custom OAuth2 Introspection

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Creates a verifier using OAuth2 introspection with a custom authentication method.

```go
auth := oauth.IntrospectionAuthenticationJWTProfile(keyFile)
verifier := oauth.WithIntrospection[*oauth.IntrospectionContext](auth)
authorizer, err := authorization.New(ctx, z, verifier)
```

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

### Generate Project Scope

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates a formatted scope string required for project-specific API access.

```go
scope := client.ScopeProjectID("my-project-id")
// Returns: "urn:zitadel:iam:org:project:id:my-project-id:aud"
```

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

### ConfigFromKeyFileData

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Parses key.json data directly from a byte slice.

```APIDOC
## func ConfigFromKeyFileData(data []byte) (*KeyFile, error)

### Description
Parses key.json data from bytes.

### Parameters
- **data** ([]byte) - Required - Raw key.json data

### Returns
- **(*KeyFile, error)** - Parsed key file or error

### Example
```go
data := []byte(`{"type":"serviceaccount",...}`)
keyFile, err := client.ConfigFromKeyFileData(data)
```
```

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

### WithGRPCDialOptions

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Allows custom gRPC dial options for the client. Multiple calls append options.

```APIDOC
## func WithGRPCDialOptions(opts ...grpc.DialOption) Option

### Description
Allows custom gRPC dial options. Multiple calls append options.

### Parameters
- **opts** (...grpc.DialOption) - Required - gRPC dial options

### Returns
- **Option** - Client option

### Example
```go
opts := []grpc.DialOption{
	grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(10 * 1024 * 1024)),
}
c, err := client.New(ctx, z, client.WithGRPCDialOptions(opts...))
```
```

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

### Configure External Secure Redirects

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Enables HTTPS redirects for services running behind a reverse proxy.

```go
func WithExternalSecure[T Ctx](externalSecure bool) Option[T]
```

```go
authenticator, err := authentication.New(
	ctx, z, key, authHandler,
	authentication.WithExternalSecure(true),
)
```

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

### Access Identity Provider Service V2

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the Identity Provider API v2.

```go
func (c *Client) IdpServiceV2() idpV2.IdentityProviderServiceClient
```

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

### Define Ctx interface

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/types.md

Interface for retrieving authentication status from context data.

```go
type Ctx interface {
	IsAuthenticated() bool
}
```

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

### Retrieve Authorization Context

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Extracts the authorization context from a standard context.Context.

```go
authCtx := authorization.Context[*oauth.IntrospectionContext](r.Context())
if authCtx.IsAuthorized() {
	userID := authCtx.UserID()
}
```

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

### Implement Logout Handler

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Using the Logout method to terminate the user session.

```go
func logoutHandler(w http.ResponseWriter, r *http.Request) {
	authenticator.Logout(w, r)
}
```

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

### PreSignedJWT

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using a pre-signed JWT token.

```APIDOC
## func PreSignedJWT(token string) TokenSourceInitializer

### Description
Creates an authentication initializer using a pre-signed JWT token.

### Parameters
- **token** (string) - Required - Pre-signed JWT token

### Returns
- **TokenSourceInitializer** - Token source initializer

### Example
```go
authOption := client.PreSignedJWT("eyJhbGc...")
c, err := client.New(ctx, z, client.WithAuth(authOption))
```
```

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

### Configure Custom gRPC Dial Options

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Appends custom gRPC dial options to the client configuration.

```go
opts := []grpc.DialOption{
	grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(10 * 1024 * 1024)),
}
c, err := client.New(ctx, z, client.WithGRPCDialOptions(opts...))
```

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

### Authenticate with Private Key JWT in Go

Source: https://github.com/zitadel/zitadel-go/blob/main/README.md

Uses a private key from a JSON file for secure production-grade authentication.

```go
package main

import (
	"context"
	"log"
	"os"
	"log/slog"

	"github.com/zitadel/oidc/v3/pkg/oidc"

	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	domain := "https://example.us1.zitadel.cloud"
	keyPath := "path/to/jwt-key.json"

	ctx := context.Background()

	authOption := client.DefaultServiceUserAuthentication(
		keyPath,
		oidc.ScopeOpenID,
		client.ScopeZitadelAPI(),
	)

	api, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))
	if err != nil {
		slog.Error("could not create api client", "error", err)
		os.Exit(1)
	}

	resp, err := api.ManagementService().GetMyOrg(ctx, &management.GetMyOrgRequest{})
	if err != nil {
		slog.Error("gRPC call failed", "error", err)
		os.Exit(1)
	}

	log.Printf("Successfully called API: Your organization is %s", resp.GetOrg().GetName())
}
```

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

### Authenticate with Personal Access Tokens (PATs) in Go

Source: https://github.com/zitadel/zitadel-go/blob/main/README.md

Uses a pre-generated token for development or testing scenarios.

```go
package main

import (
	"context"
	"log"
	"os"
	"log/slog"

	"github.com/zitadel/zitadel-go/v3/pkg/client"
	"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management"
	"github.com/zitadel/zitadel-go/v3/pkg/zitadel"
)

func main() {
	domain := "https://example.us1.zitadel.cloud"
	token := "token"

	ctx := context.Background()

	authOption := client.PAT(token)

	api, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))
	if err != nil {
		slog.Error("could not create api client", "error", err)
		os.Exit(1)
	}

	resp, err := api.ManagementService().GetMyOrg(ctx, &management.GetMyOrgRequest{})
	if err != nil {
		slog.Error("gRPC call failed", "error", err)
		os.Exit(1)
	}

	log.Printf("Successfully called API: Your organization is %s", resp.GetOrg().GetName())
}
```

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

### Define Option Type

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Function type for configuring Authorizer.

```go
type Option[T Ctx] func(authorizer *Authorizer[T])
```

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

### Implement Callback Handler

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Using the Callback method to process the OIDC response.

```go
func callbackHandler(w http.ResponseWriter, r *http.Request) {
	authenticator.Callback(w, r)
}
```

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

### Retrieve Authentication Context

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Extracts the authentication context from a standard context.Context.

```go
authCtx := authentication.Context[*UserContext](r.Context())
if authCtx.IsAuthenticated() {
	// User is authenticated
}
```

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

### Initialize Default OAuth2 Authorization

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Creates a token verifier using OAuth2 introspection with JWT Profile authentication.

```go
verifier := oauth.DefaultAuthorization("path/to/key.json")
authorizer, err := authorization.New(ctx, z, verifier)
if err != nil {
	log.Fatal(err)
}
```

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

### Inject Authorization Context

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Stores an authorization context into a context.Context.

```go
newCtx := authorization.WithAuthContext(r.Context(), authCtx)
```

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

### Implement API Authorization Middleware

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/INDEX.md

Validates Authorization headers and enforces role requirements before proceeding to the next handler.

```go
func requireAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		token := r.Header.Get("Authorization")
		authCtx, err := authorizer.CheckAuthorization(
			r.Context(),
			token,
			authorization.WithRole("api_user"),
		)
		if err != nil {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}
		ctx := authorization.WithAuthContext(r.Context(), authCtx)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}
```

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

### Set Authorization Token

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authorization.md

Stores the provided authorization token within the context.

```go
func (c *IntrospectionContext) SetToken(token string)
```

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

### Configure Authenticator Logger

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Sets a custom slog logger for the authenticator instance.

```go
func WithLogger[T Ctx](logger *slog.Logger) Option[T]
```

```go
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
authenticator, err := authentication.New(
	ctx, z, key, authHandler,
	authentication.WithLogger(logger),
)
```

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

### SAMLServiceV2

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Returns the client for the SAML API v2.

```APIDOC
## func (c *Client) SAMLServiceV2()

### Description
Returns the client for the SAML API v2.

### Returns
- **samlV2.SAMLServiceClient** - Client for SAML API v2
```

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

### Define Ctx Interface

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/types.md

Interface for managing authorization context data, including user roles and token storage.

```go
type Ctx interface {
	IsAuthorized() bool
	OrganizationID() string
	UserID() string
	IsGrantedRole(role string) bool
	IsGrantedRoleInProject(projectID, role, organizationID string) bool
	IsGrantedRoleInOrganization(role, organizationID string) bool
	SetToken(token string)
	GetToken() string
}
```

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

### PasswordAuthentication

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-client.md

Creates an authentication initializer using OAuth2 Client Credentials Grant.

```APIDOC
## func PasswordAuthentication(username, password string, scopes ...string) TokenSourceInitializer

### Description
Creates an authentication initializer using OAuth2 Client Credentials Grant.

### Parameters
- **username** (string) - Required - Client ID
- **password** (string) - Required - Client secret
- **scopes** (...string) - Optional - OAuth2 scopes

### Returns
- **TokenSourceInitializer** - Token source initializer

### Example
```go
authOption := client.PasswordAuthentication(
	"client-id",
	"client-secret",
	oidc.ScopeOpenID,
	client.ScopeZitadelAPI(),
)
c, err := client.New(ctx, z, client.WithAuth(authOption))
```
```

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

### Mount Authenticator Routes

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Mounting the authenticator to an HTTP handler to manage login, callback, and logout routes.

```go
http.Handle("/auth/", authenticator)
http.ListenAndServe(":8080", nil)
```

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

### Define and Handle ErrInvalidHeader

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/errors.md

Error returned when the ZITADEL-Signature header format is malformed.

```go
var ErrInvalidHeader = errors.New("webhook has invalid Zitadel-Signature header")
```

```go
err := actions.ValidatePayload(payload, sigHeader, signingKey)
if err == actions.ErrInvalidHeader {
	log.Println("Webhook signature header format error")
	http.Error(w, "Bad request", http.StatusBadRequest)
	return
}
```

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

### func New

Source: https://github.com/zitadel/zitadel-go/blob/main/_autodocs/api-reference-authentication.md

Creates a new Authenticator instance for handling OIDC login flows.

```APIDOC
## func New[T Ctx]

### Description
Creates an Authenticator for handling OIDC login flows.

### Parameters
- **ctx** (context.Context) - Required - Initialization context
- **zitadel** (*zitadel.Zitadel) - Required - Zitadel instance configuration
- **encryptionKey** (string) - Required - Key for encrypting state and sessions (min 32 chars recommended)
- **initAuthentication** (HandlerInitializer[T]) - Required - Authentication handler initializer (e.g., OIDC handler)
- **options** (...Option[T]) - Optional - Optional configuration

### Returns
- (*Authenticator[T], error) - Initialized authenticator or error
```
Tokens:
Raw