OIDC

https://github.com/zitadel/oidc
Admin
OIDC is an OpenID Connect SDK for Go providing easy-to-use client (RP) and server (OP)...
Tokens:355,535
Snippets:1,795
Trust Score:9.5
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Usage example

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

Example of creating an OpenID Connect provider using the op package, including configuration and mounting as an HTTP handler.

```APIDOC
## Usage example

### Description
Example of creating an OpenID Connect provider using the op package, including configuration and mounting as an HTTP handler.

### Code
```go
storage := myStorage{} // implements op.Storage (see op-storage.md)
key := sha256.Sum256([]byte("32-byte-crypto-key"))

provider, err := op.NewProvider(&op.Config{
	CryptoKey:            key,
	CryptoKeyId:          "key1",
	CodeMethodS256:       true,
	AuthMethodPost:       true,
	GrantTypeRefreshToken: true,
	DeviceAuthorization: op.DeviceAuthorizationConfig{
		Lifetime:     5 * time.Minute,
		PollInterval: 5 * time.Second,
		UserFormPath: "/device",
		UserCode:     op.UserCodeBase20,
	},
}, storage, op.StaticIssuer("https://oidc.example.com"))

if err != nil {
	log.Fatal(err)
}

// provider is an http.Handler — mount it
http.ListenAndServe(":8080", op.CreateRouter(provider))
```
```

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

### Run OIDC OP server with dynamic issuer

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

Starts the OIDC OP server with a dynamic issuer. The web client from the previous example still works, but you can also use oidc.local (pointing to 127.0.0.1) in your hosts file to start the client with ISSUER=http://oidc.local:9998/.

```bash
go run github.com/zitadel/oidc/v3/example/server/dynamic
```

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

### Example: Introspect with client credentials

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

Example of creating a `ResourceServer` with client credentials and calling `Introspect` to validate an access token. Checks the `Active` field to determine token validity.

```go
// Example
rs, err := rs.NewResourceServerClientCredentials(ctx, "https://issuer.example.com", "api-client", "secret")
if err != nil {
	log.Fatal(err)
}
var resp oidc.IntrospectionResponse
if err := rs.Introspect(ctx, rs, accessToken); err != nil {
	// introspection failed
}
if !resp.Active {
	// token invalid or expired
}
```

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

### Example: state + PKCE cookies for an RP

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

Example usage of CookieHandler to set a state cookie and check it via CheckQueryCookie. Uses WithUnsecure option. The SetCookie call may fail; the error is handled inline.

```go
// Example: state + PKCE cookies for an RP
cookieHandler := httphelper.NewCookieHandler(hashKey, encKey, httphelper.WithUnsecure())
if err := cookieHandler.SetCookie(w, "state", stateValue); err != nil { /* ... */ }
value, err := cookieHandler.CheckQueryCookie(r, "state")
```

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

### Example user JSON for USERS_FILE

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

JSON structure for a user entry in the USERS_FILE used by the example server. Shows the fields for user data and credentials, including ID, Username, Password, Email, and verification flags.

```json
{
  "id2": {
    "ID": "id2",
    "Username": "test-user2",
    "Password": "verysecure",
    "FirstName": "Test",
    "LastName": "User2",
    "Email": "test-user2@zitadel.ch",
    "EmailVerified": true,
    "Phone": "",
    "PhoneVerified": false,
    "PreferredLanguage": "DE",
    "IsAdmin": false
  }
}
```

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

### Example handler wiring

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

Example of wiring the authorization URL handler and code exchange handler in an HTTP server. The login handler generates a state and redirects to the provider, while the callback handler exchanges the code and prints the subject.

```go
// Example handler wiring
http.HandleFunc("/login", rp.AuthURLHandler(func() string { return uuid.NewString() }, provider))
http.HandleFunc("/auth/callback", rp.CodeExchangeHandler(func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens[*oidc.IDTokenClaims], state string, provider rp.RelyingParty) {
	// tokens.IDTokenClaims, tokens.IDToken, tokens.AccessToken available
	fmt.Fprintf(w, "logged in as %s", tokens.IDTokenClaims.GetSubject())
}, provider))
```

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

### StartServer

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

Starts an HTTP server on the given address in a goroutine and shuts it down when the context is cancelled. Logs fatal errors on non-ErrServerClosed failures.

```APIDOC
## StartServer

### Description
Starts `http.ListenAndServe(address)` in a goroutine, and a second goroutine that shuts it down (5s timeout) when `ctx` is cancelled. `log.Fatalf` on non-`http.ErrServerClosed` listen/shutdown errors. Used by `rp/cli.CodeFlow`.

### Function Signature
```go
func StartServer(ctx context.Context, address string)
```

### Parameters
- **ctx** (context.Context) - Required - The context that controls server shutdown.
- **address** (string) - Required - The network address to listen on (e.g., ":8080").

### Behavior
- Starts the server in a goroutine.
- On context cancellation, shuts down the server with a 5-second timeout.
- Calls `log.Fatalf` on any listen/shutdown error other than `http.ErrServerClosed`.
```

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

### Example: impersonation exchange

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

Shows how to perform an impersonation token exchange using client credentials, with error handling for InvalidTarget.

```go
// Example: impersonation exchange
te, err := tokenexchange.NewTokenExchangerClientCredentials(ctx, issuer, "client-a", "secret")
if err != nil { /* ... */ }

resp, err := tokenexchange.ExchangeToken(ctx, te,
	userAccessToken, oidc.AccessTokenType, // subject token
	"", "",                                 // no actor token
	nil, []string{"api-backend"},           // resource, audience
	nil, oidc.AccessTokenType,               // scopes, requested token type
)
if err != nil {
	var oidcErr *oidc.Error
	if errors.As(err, &oidcErr) && oidcErr.ErrorType == oidc.InvalidTarget {
		// audience not allowed
	}
}
// resp.AccessToken is valid for "api-backend"
```

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

### Example: Creating an OIDC Relying Party

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

Example of creating an OIDC Relying Party with PKCE and a custom HTTP client. The `cookieHandler` is created with `httphelper.NewCookieHandler(hashKey, encryptKey, ...)`. On failure, handle discovery or option errors.

```go
rp, err := rp.NewRelyingPartyOIDC(ctx, "https://issuer.example.com",
	"client-web", "secret", "https://app.example.com/auth/callback", []string{"openid", "profile"},
	rp.WithPKCE(cookieHandler), // cookieHandler: httphelper.NewCookieHandler(hashKey, encryptKey, ...)
	rp.WithHTTPClient(httpClient),
)
if err != nil { /* discovery or option failure */ }
```

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

### Example: creating a JWT Profile token source and obtaining a token

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

Shows how to create a token source using `NewJWTProfileTokenSource` with a custom HTTP client, then obtain a token via `TokenCtx` or `Token`.

```go
// Example
ts, err := profile.NewJWTProfileTokenSource(ctx, "https://issuer.example.com",
	"service-account", "key-1", pemKey, []string{"openid"},
	profile.WithHTTPClient(myClient),
)
if err != nil { /* signer or discovery error */ }

token, err := ts.TokenCtx(ctx) // or ts.Token()
if err != nil { /* token request error */ }
// token.AccessToken is now usable
```

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

### Run OIDC OP server and web client

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

Starts the OIDC OP server and the web client. The OP server runs on port 9998 and the client on port 9999. After starting, open http://localhost:9999/login in a browser, log in with test-user@localhost and password verysecure, and the OP redirects to the client app displaying user info.

```bash
# start oidc op server
# oidc discovery http://localhost:9998/.well-known/openid-configuration
go run github.com/zitadel/oidc/v3/example/server
# start oidc web client (in a new terminal)
CLIENT_ID=web CLIENT_SECRET=secret ISSUER=http://localhost:9998/ SCOPES="openid profile" PORT=9999 go run github.com/zitadel/oidc/v3/example/client/app
```

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

### Example: serve legacy provider through new Server plumbing

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-server.md

Shows how to register a legacy provider using RegisterLegacyServer with an authorize callback handler, then serve it on port 8080. The handler is created via op.AuthorizeCallbackHandler(provider).

```go
// Example: serve the legacy provider through the new Server plumbing
handler := op.RegisterLegacyServer(
	op.NewLegacyServer(provider, provider.Endpoints()),
	op.AuthorizeCallbackHandler(provider),
)
http.ListenAndServe(":8080", handler)
```

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

### Device flow polling example

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

Example of calling the device authorization endpoint and polling for the access token. Handles oidc.AccessDenied and oidc.ExpiredToken errors.

```go
// Example: device flow polling
resp, err := client.CallDeviceAuthorizationEndpoint(ctx, &oidc.ClientCredentialsRequest{
	ClientID: "device-client",
	Scope:    oidc.SpaceDelimitedArray{"openid", "profile"},
}, caller, httphelper.AuthorizeBasic("device-client", "secret"))
if err != nil { /* handle */ }

tokens, err := client.PollDeviceAccessTokenEndpointWithAuthFn(ctx, time.Duration(resp.Interval)*time.Second, &client.DeviceAccessTokenRequest{
	DeviceAccessTokenRequest: oidc.DeviceAccessTokenRequest{
		GrantType:  oidc.GrantTypeDeviceCode,
		DeviceCode: resp.DeviceCode,
	},
}, caller, httphelper.AuthorizeBasic("device-client", "secret"))
if err != nil {
	var oidcErr *oidc.Error
	if errors.As(err, &oidcErr) {
		switch oidcErr.ErrorType {
		case oidc.AccessDenied:
			// user denied
		case oidc.ExpiredToken:
			// device code expired
		}
	}
}
```

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

### Import client package

Source: https://github.com/zitadel/oidc/blob/main/UPGRADING.md

Import statement for the client package, shown in the upgrade guide under the client section.

```go
import "github.com/zitadel/oidc/v3/pkg/client"
```

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

### Usage example: creating an OIDC provider

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

Shows how to instantiate an OIDC provider with a custom storage, a crypto key, and various configuration options including device authorization. The provider is an http.Handler and can be mounted using op.CreateRouter.

```go
storage := myStorage{} // implements op.Storage (see op-storage.md)
key := sha256.Sum256([]byte("32-byte-crypto-key"))

provider, err := op.NewProvider(&op.Config{
	CryptoKey:            key,
	CryptoKeyId:          "key1",
	CodeMethodS256:       true,
	AuthMethodPost:       true,
	GrantTypeRefreshToken: true,
	DeviceAuthorization: op.DeviceAuthorizationConfig{
		Lifetime:     5 * time.Minute,
		PollInterval: 5 * time.Second,
		UserFormPath: "/device",
		UserCode:     op.UserCodeBase20,
	},
}, storage, op.StaticIssuer("https://oidc.example.com"))

if err != nil {
	log.Fatal(err)
}

// provider is an http.Handler — mount it
http.ListenAndServe(":8080", op.CreateRouter(provider))
```

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

### Usage example: AES-256-GCM crypto and custom provider

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-crypto.md

Demonstrates encrypting and decrypting opaque access tokens with `NewAES256GCMCrypto` and passing a custom crypto to `NewProvider` via `WithCrypto`. The example uses a 32-byte key and a key ID.

```go
// Encrypt/decrypt opaque access tokens with AES-256-GCM
cryptoImpl := op.NewAES256GCMCrypto([32]byte("super-secret-key-0123456789abcdef"), "key1")
encrypted, err := cryptoImpl.Encrypt("tokenID:subject")
if err != nil { /* ... */ }
plain, err := cryptoImpl.Decrypt(encrypted)
if err != nil { /* ... */ }

// Pass a custom crypto to the provider
provider, err := op.NewProvider(cfg, storage, issuer, op.WithCrypto(cryptoImpl))
```

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

### Token Verification Usage Example

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

Example of verifying an ID token using the Verifier and Check* functions.

```APIDOC
## Token Verification Usage Example

### Description
Example of verifying an ID token using the Verifier and Check* functions.

### Code Example
```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

var claims *oidc.IDTokenClaims
payload, err := oidc.ParseToken(idToken, &claims)
if err != nil {
	// parsing of request failed
	return
}

verifier := oidc.Verifier{
	Issuer:   "https://issuer.example.com",
	ClientID: "client-web",
	KeySet:   keyset, // e.g. rp.NewRemoteKeySet(client, jwksURL)
	Offset:   time.Second,
}
_ = oidc.CheckIssuerWithISSVerifier(claims, verifier.Issuer, verifier.ISS)
_ = oidc.CheckAudience(claims, verifier.ClientID)
_ = oidc.CheckSignature(ctx, idToken, payload, claims, verifier.SupportedSignAlgs, verifier.KeySet)
if err := oidc.CheckExpiration(claims, verifier.Offset); err != nil {
	// token has expired
}
if err := oidc.CheckIssuedAt(claims, verifier.MaxAgeIAT, verifier.Offset); err != nil {
	// iat missing / in future / too old
}
```

### Notes
For simple use cases prefer the higher-level `rp.VerifyIDToken` / `rp.VerifyTokens`.
```

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

### Go storage skeleton implementing op.Storage

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-storage.md

Use this skeleton as a starting point for implementing the op.Storage interface. It includes placeholder methods for GetClientByClientID, AuthorizeClientIDSecret, and Health, and a compile-time check to ensure the type satisfies the interface. You must implement the remaining AuthStorage and OPStorage methods.

```go
type storage struct{ /* db handles */ }

func (s *storage) GetClientByClientID(ctx context.Context, clientID string) (op.Client, error) { /* ... */ }
func (s *storage) AuthorizeClientIDSecret(ctx context.Context, clientID, clientSecret string) error { /* ... */ }
func (s *storage) Health(ctx context.Context) error { return nil }
// ... implement the remaining AuthStorage / OPStorage methods

var _ op.Storage = (*storage)(nil) // compile-time check
```

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

### Embedding UnimplementedServer in a custom server

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-server.md

Shows how to embed op.UnimplementedServer to get default implementations for all Server methods, then override only the supported ones.

```go
type myServer struct {
	op.UnimplementedServer
}
// override Health, Discovery, CodeExchange, ...
```

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

### Authorization Code Flow - Complete Example

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

Demonstrates the full authorization code flow using RelyingPartyOIDC, including login redirect, callback handling, and token verification.

```APIDOC
## Authorization Code Flow - Complete Example

### Description
Shows how to set up a relying party, redirect to the provider, handle the callback, and verify tokens.

### Usage
```go
// state + error handling omitted for brevity — see AuthURLHandler/CodeExchangeHandler
provider, err := rp.NewRelyingPartyOIDC(ctx, issuer, clientID, clientSecret, redirectURI, scopes,
	rp.WithPKCE(cookieHandler),
	rp.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)
if err != nil {
	log.Fatal(err)
}

// 1. redirect to provider
http.HandleFunc("/login", rp.AuthURLHandler(func() string { return uuid.NewString() }, provider))

// 2. callback
http.HandleFunc("/auth/callback", rp.CodeExchangeHandler(func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens[*oidc.IDTokenClaims], state string, provider rp.RelyingParty) {
	// 3. verify + read claims
	claims, err := rp.VerifyTokens[*oidc.IDTokenClaims](r.Context(), tokens.AccessToken, tokens.IDToken, provider.IDTokenVerifier())
	if err != nil {
		rp.ErrorHandler()(w, r, "invalid_id_token", err.Error(), state)
		return
	}
	json.NewEncoder(w).Encode(claims)
}, provider, rp.WithURLParam("prompt", "login")))
```
```

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

### StartServer function signature

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

Starts http.ListenAndServe(address) in a goroutine and a second goroutine that shuts it down (5s timeout) when ctx is cancelled. Logs fatal on non-http.ErrServerClosed errors. Used by rp/cli.CodeFlow.

```go
func StartServer(ctx context.Context, address string)
```

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

### Usage example for verifying ID tokens

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

Shows how to parse an ID token and verify its claims using the oidc.Verifier and KeySet. Includes checks for issuer, audience, signature, expiration, and issued-at time.

```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

var claims *oidc.IDTokenClaims
payload, err := oidc.ParseToken(idToken, &claims)
if err != nil {
	// parsing of request failed
	return
}

verifier := oidc.Verifier{
	Issuer:   "https://issuer.example.com",
	ClientID: "client-web",
	KeySet:   keyset, // e.g. rp.NewRemoteKeySet(client, jwksURL)
	Offset:   time.Second,
}
_ = oidc.CheckIssuerWithISSVerifier(claims, verifier.Issuer, verifier.ISS)
_ = oidc.CheckAudience(claims, verifier.ClientID)
_ = oidc.CheckSignature(ctx, idToken, payload, claims, verifier.SupportedSignAlgs, verifier.KeySet)
if err := oidc.CheckExpiration(claims, verifier.Offset); err != nil {
	// token has expired
}
if err := oidc.CheckIssuedAt(claims, verifier.MaxAgeIAT, verifier.Offset); err != nil {
	// iat missing / in future / too old
}
```

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

### GET /.well-known/openid-configuration

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/endpoints.md

Returns the OpenID Connect discovery configuration for the provider.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Returns the OpenID Connect discovery configuration, including supported endpoints, grant types, and token endpoint auth methods.

### Method
GET

### Endpoint
/.well-known/openid-configuration

### Response
#### Success Response (200)
- **issuer** (string) - The issuer URL.
- **authorization_endpoint** (string) - The authorization endpoint URL.
- **token_endpoint** (string) - The token endpoint URL.
- **jwks_uri** (string) - The JWKS URI.
- **grant_types_supported** (array of string) - Supported grant types.
- **token_endpoint_auth_methods_supported** (array of string) - Supported client authentication methods.
- ... (other fields as per oidc.DiscoveryConfiguration)

#### Response Example
{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "jwks_uri": "https://example.com/keys",
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"]
}
```

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

### Run OIDC web client with dynamic issuer

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

Starts the OIDC web client using the dynamic issuer URL http://oidc.local:9998/. Requires adding oidc.local pointing to 127.0.0.1 in the hosts file. Usernames are suffixed with the hostname, e.g., test-user@oidc.local.

```bash
CLIENT_ID=web CLIENT_SECRET=secret ISSUER=http://oidc.local:9998/ SCOPES="openid profile" PORT=9999 go run github.com/zitadel/oidc/v3/example/client/app
```

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

### Verify access token example

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-verifiers.md

Verifies a bearer token using VerifyAccessToken. On error, returns HTTP 401. The claims include Subject, JWTID, Scopes, and Claims.

```go
// Example: verify a bearer token presented to a resource endpoint
claims, err := op.VerifyAccessToken[*oidc.AccessTokenClaims](r.Context(), bearerToken, provider.AccessTokenVerifier(r.Context()))
if err != nil {
	http.Error(w, "invalid access token", http.StatusUnauthorized)
	return
}
// claims.Subject, claims.JWTID, claims.Scopes, claims.Claims ...
```

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

### NewResourceServerFromKeyFile

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

Creates a ResourceServer from a deprecated key file format. It runs discovery unless static endpoints are provided.

```APIDOC
## NewResourceServerFromKeyFile

### Description
Creates a ResourceServer from a deprecated key file format. It runs discovery unless static endpoints are provided.

### Method
Constructor

### Signature
func NewResourceServerFromKeyFile(ctx context.Context, issuer, path string, options ...Option) (ResourceServer, error)

### Parameters
- **ctx** (context.Context) - Required - Used for the discovery call.
- **issuer** (string) - Required - OP issuer.
- **path** (string) - Required - Key file path (deprecated key file format).
- **options** (Option) - Optional - Variadic options, e.g., WithClient, WithStaticEndpoints.

### Return
- **ResourceServer** - The constructed ResourceServer.
- **error** - Error if discovery fails or token URL is empty.

### Errors
- Returns an error if the token URL is empty after discovery: "tokenURL is empty: please provide with either `WithStaticEndpoints` or a discovery url".
```

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

### Complete authorization code flow with PKCE and token verification

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

Shows the full authorization code flow: create a relying party with PKCE and custom HTTP client, then set up handlers for login redirect and callback. The callback exchanges the code for tokens, verifies them, and encodes claims as JSON. State and error handling are omitted for brevity.

```go
// state + error handling omitted for brevity — see AuthURLHandler/CodeExchangeHandler
provider, err := rp.NewRelyingPartyOIDC(ctx, issuer, clientID, clientSecret, redirectURI, scopes,
	rp.WithPKCE(cookieHandler),
	rp.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)
if err != nil {
	log.Fatal(err)
}

// 1. redirect to provider
http.HandleFunc("/login", rp.AuthURLHandler(func() string { return uuid.NewString() }, provider))

// 2. callback
http.HandleFunc("/auth/callback", rp.CodeExchangeHandler(func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens[*oidc.IDTokenClaims], state string, provider rp.RelyingParty) {
	// 3. verify + read claims
	claims, err := rp.VerifyTokens[*oidc.IDTokenClaims](r.Context(), tokens.AccessToken, tokens.IDToken, provider.IDTokenVerifier())
	if err != nil {
		rp.ErrorHandler()(w, r, "invalid_id_token", err.Error(), state)
		return
	}
	json.NewEncoder(w).Encode(claims)
}, provider, rp.WithURLParam("prompt", "login")))
```

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

### GET /ready

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/endpoints.md

Readiness probe that returns 200 when all internal probes pass, otherwise 500.

```APIDOC
## GET /ready

### Description
Readiness probe that indicates whether the service is ready to serve traffic. Returns 200 when all probes pass, otherwise 500.

### Method
GET

### Endpoint
/ready

### Response
#### Success Response (200)
- **status** (string) - Always "ok".

#### Response Example
{
  "status": "ok"
}

#### Error Response (500)
- **body** (string) - "not ready" when any probe fails.
```

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

### GET /healthz

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/endpoints.md

Health check endpoint that returns a simple status indicating the service is alive.

```APIDOC
## GET /healthz

### Description
Returns a simple status indicating the service is healthy and running.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **status** (string) - Always "ok".

#### Response Example
{
  "status": "ok"
}
```

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

### GET keys

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/endpoints.md

Returns the JSON Web Key Set (JWKS) containing the provider's public keys.

```APIDOC
## GET keys

### Description
Returns the JSON Web Key Set (JWKS) containing the provider's public keys used for verifying signatures.

### Method
GET

### Endpoint
keys

### Response
#### Success Response (200)
- **keys** (array of JWK) - Array of JSON Web Keys, each with fields like kty, use, kid, alg.

#### Response Example
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256"
    }
  ]
}

#### Error Response (500)
- **error** (object) - oidc.Error shape when storage error occurs.
```

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

### GET /keys

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-endpoints.md

Serializes the storage's Key list into a jose.JSONWebKeySet JSON document. Storage errors result in a 500 status code.

```APIDOC
## [GET] /keys

### Description
Serializes the storage's `Key` list into a `jose.JSONWebKeySet` JSON document (`kid`, `alg`, `use`, `key`). Storage errors → 500.

### Method
GET

### Endpoint
/keys

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **kid** (string) - Key identifier
- **alg** (string) - Algorithm
- **use** (string) - Usage
- **key** (object) - Key data

#### Response Example
{
  "keys": [
    {
      "kid": "string",
      "alg": "string",
      "use": "string",
      "key": {}
    }
  ]
}

### Error Handling
- **500** - Storage error
```

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

### KeyFile struct and config functions (deprecated)

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

KeyFile represents a service account or application key file. ConfigFromKeyFile and ConfigFromKeyFileData load the configuration from a file path or raw data. Deprecated in favor of github.com/zitadel/zitadel-go/v3/pkg/client.

```go
type KeyFile struct {
	Type   string `json:"type"` // serviceaccount or application
	KeyID  string `json:"keyId"`
	Key    string `json:"key"`
	Issuer string `json:"issuer"` // not yet in file
	UserID string `json:"userId"` // serviceaccount
	ClientID string `json:"clientId"` // application
}

func ConfigFromKeyFile(path string) (*KeyFile, error)
func ConfigFromKeyFileData(data []byte) (*KeyFile, error)
```

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

### Catching errors in consumer code

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

Examples of how to catch and handle errors from the OIDC library, including protocol errors, sentinel errors, and status errors.

```APIDOC
## Catching errors in consumer code

### Description
This section provides code examples for catching and handling errors from the OIDC library in consumer code.

### Code Example
```go
// 1. protocol errors (HTTP level)
if err := callTokenEndpoint(ctx, ...); err != nil {
	var oidcErr *oidc.Error
	if errors.As(err, &oidcErr) {
		// oidcErr.ErrorType / oidcErr.Description
	}
}

// 2. sentinel comparisons
if errors.Is(err, oidc.ErrExpired)     { /* retry flow */ }
if errors.Is(err, rp.ErrInvalidOption) { /* fix RP options */ }

// 3. status-aware server implementations
var statusError op.StatusError
if errors.As(err, &statusError) { /* statusError (unexported) status via Unwrap chain */ }
```
```

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

### Locale struct definition

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

Defines the Locale struct with an unexported language.Tag field. It provides methods for construction, getting the tag, stringification, and JSON marshaling/unmarshaling.

```go
type Locale struct {
	tag language.Tag // unexported
}

```

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

### Fetch discovery with client.Discover

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

Shows how to fetch OIDC discovery information using client.Discover. On error, it wraps oidc.ErrDiscoveryFailed or oidc.ErrIssuerInvalid. Checks CodeChallengeMethodsSupported to see if the OP supports PKCE.

```go
// Client side: fetch discovery
config, err := client.Discover(ctx, issuer, http.DefaultClient)
if err != nil {
	// wraps oidc.ErrDiscoveryFailed or oidc.ErrIssuerInvalid
	return
}
if len(config.CodeChallengeMethodsSupported) > 0 {
	// OP supports PKCE
}
```

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

### Endpoint

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

The Endpoint type represents a URL path or full URL. It provides constructors and methods to get relative and absolute URL strings, and to validate the endpoint.

```APIDOC
## Endpoint

### Description
The Endpoint type represents a URL path or full URL. It provides constructors and methods to get relative and absolute URL strings, and to validate the endpoint.

### Type
`type Endpoint struct { /* unexported path/url fields */ }`

### Constructors

#### NewEndpoint(path string) *Endpoint
Creates a new Endpoint from a path.

#### NewEndpointWithURL(path, url string) *Endpoint
Creates a new Endpoint with a static URL.

### Methods

#### Relative() string
Returns the relative path (prefixed with "/") or empty string for nil endpoint.

#### Absolute(host string) string
Returns the static URL if set, otherwise the host concatenated with the relative path.

#### Validate() error
Returns ErrNilEndpoint for nil endpoint; path checks are TODO.

### Errors
- `ErrNilEndpoint` - returned when the endpoint is nil.
```

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

### ConfigFromKeyFile (Deprecated)

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

Loads a KeyFile from a file path. Deprecated.

```APIDOC
## ConfigFromKeyFile (Deprecated)

### Description
Loads a KeyFile from a file path. Deprecated in favor of `github.com/zitadel/zitadel-go/v3/pkg/client`.

### Function Signature
```go
func ConfigFromKeyFile(path string) (*KeyFile, error)
```

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

### Return Values
- **keyFile** (*KeyFile) - The parsed key file.
- **err** (error) - An error if the file cannot be read or parsed.
```

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

### DPoP / Key Binding 1.0 helpers (dpop.go)

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

Experimental helpers for DPoP / Key Binding 1.0. Includes Confirmation struct, DPoPProofClaims struct, and functions for validating DPoP JWK thumbprints, key strength, and code hash.

```go
type Confirmation struct {
	JWK json.RawMessage `json:"jwk"` // cnf claim of a key-bound ID Token
}

type DPoPProofClaims struct {
	JWTID      string `json:"jti"`
	HTTPMethod string `json:"htm"`
	HTTPURI    string `json:"htu"`
	IssuedAt   Time   `json:"iat"`
	CodeHash   string `json:"c_s256,omitempty"`
}

func ValidDPoPJKT(value string) bool                                        // unpadded base64url SHA-256 thumbprint?
func JWKThumbprint(jwk *jose.JSONWebKey) (string, error)                    // RFC 7638 SHA-256 thumbprint, unpadded base64url
func ValidateDPoPKeyStrength(key any) error                                 // RSA 2048–8192 bits, EC P-256/384/521; others pass
func CodeHash(code string) string                                           // c_s256 = SHA-256(code), unpadded base64url
func (c *DPoPProofClaims) UnmarshalJSON(data []byte) error                  // rejects null iat
```

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

### Verify JWT assertion example

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-verifiers.md

Verifies a client_assertion JWT using VerifyJWTAssertion. On error, the assertion is invalid. The clientID is taken from req.Issuer, which matches req.Subject when SubjectIsIssuer is used.

```go
// Example: verify a client_assertion JWT
req, err := op.VerifyJWTAssertion(ctx, assertion, provider.JWTProfileVerifier(ctx))
if err != nil {
	// invalid assertion
	return
}
clientID := req.Issuer // matches req.Subject when SubjectIsIssuer is used
```

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

### Key binding interface and errors (key_binding.go)

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

Defines the experimental key binding interface and its error variables. `KeyBindingThumbprint()` returns "" when not configured, and `SignDPoPProof` returns `ErrInvalidKeyBinding` when no key binding is configured. DPoP proofs are only signed for the configured token endpoint, and redirects of token requests are refused.

```go
var (
	ErrInvalidKeyBinding     = errors.New("invalid key binding configuration")
	ErrKeyBindingIDToken     = errors.New("invalid key-bound ID token")
	ErrKeyBindingConfirmation = errors.New("ID token confirmation does not match the binding key")
	ErrKeyBindingEndpoint    = errors.New("key-bound request refused for a URL other than the token endpoint")
)

type KeyBindingRelyingParty interface {
	RelyingParty
	KeyBindingThumbprint() string
	SignDPoPProof(method, htu, code string) (string, error)
}
```

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

### IntrospectionResponse methods

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

Methods on `IntrospectionResponse` for setting user info, getting the address nil-safely, and custom JSON marshaling. `MarshalJSON` makes `Username` fall back to `PreferredUsername`.

```go
func (i *IntrospectionResponse) SetUserInfo(u *UserInfo)                  // copies sub/username/address/profile/email/phone + merges claims
func (i *IntrospectionResponse) GetAddress() *UserInfoAddress             // nil-safe
func (i *IntrospectionResponse) MarshalJSON() ([]byte, error)             // Username falls back to PreferredUsername
func (i *IntrospectionResponse) UnmarshalJSON(data []byte) error
```

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

### ResourceServer constructors

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

Constructors for creating a `ResourceServer` using client credentials, JWT profile, or a key file. They run discovery unless static endpoints are provided.

```go
func NewResourceServerClientCredentials(ctx context.Context, issuer, clientID, clientSecret string, option ...Option) (ResourceServer, error)
func NewResourceServerJWTProfile(ctx context.Context, issuer, clientID, keyID string, key []byte, options ...Option) (ResourceServer, error)
func NewResourceServerFromKeyFile(ctx context.Context, issuer, path string, options ...Option) (ResourceServer, error)
```

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

### Import op package

Source: https://github.com/zitadel/oidc/blob/main/UPGRADING.md

Shows the import statement for the op package in v3.

```go
import "github.com/zitadel/oidc/v3/pkg/op"

```

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

### ResourceServer options

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

Options for customizing the `ResourceServer`, including a custom HTTP client and static endpoints.

```go
type Option func(*resourceServer)

func WithClient(client *http.Client) Option          // custom HTTP client
func WithStaticEndpoints(tokenURL, introspectURL string) Option
```

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

### Catch *oidc.Error with errors.As and switch on ErrorType

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

Use errors.As to unwrap a *oidc.Error and switch on its ErrorType field. The example shows handling AuthorizationPending and SlowDown for device flow polling, and InvalidClient for HTTP 401 semantics.

```go
var oidcErr *oidc.Error
if errors.As(err, &oidcErr) {
	switch oidcErr.ErrorType {
	case oidc.AuthorizationPending, oidc.SlowDown:
		// device flow: keep polling
	case oidc.InvalidClient:
		// HTTP 401 semantics
	}
}
```

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

### Import for client/rp

Source: https://github.com/zitadel/oidc/blob/main/UPGRADING.md

Import statement for the client/rp package.

```go
import "github.com/zitadel/oidc/v3/pkg/client/rs"
```

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

### NewResourceServerClientCredentials

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

Creates a ResourceServer using client credentials (basic auth) for token introspection. It runs discovery unless static endpoints are provided.

```APIDOC
## NewResourceServerClientCredentials

### Description
Creates a ResourceServer using client credentials (basic auth) for token introspection. It runs discovery unless static endpoints are provided.

### Method
Constructor

### Signature
func NewResourceServerClientCredentials(ctx context.Context, issuer, clientID, clientSecret string, option ...Option) (ResourceServer, error)

### Parameters
- **ctx** (context.Context) - Required - Used for the discovery call.
- **issuer** (string) - Required - OP issuer; also the audience of JWT profile assertions.
- **clientID** (string) - Required - Client identifier for basic auth.
- **clientSecret** (string) - Required - Client secret for basic auth.
- **option** (Option) - Optional - Variadic options, e.g., WithClient, WithStaticEndpoints.

### Return
- **ResourceServer** - The constructed ResourceServer.
- **error** - Error if discovery fails or token URL is empty.

### Errors
- Returns an error if the token URL is empty after discovery: "tokenURL is empty: please provide with either `WithStaticEndpoints` or a discovery url".
```

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

### GET /userinfo

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-endpoints.md

Resolves the access token from the Authorization header or access_token form field, decrypts or verifies it, and returns the user info as JSON. Missing or invalid tokens return 401, storage errors return 403.

```APIDOC
## [GET] /userinfo

### Description
Token resolution: `Authorization: Bearer <token>` header first, then the `access_token` form field. Token → tokenID/subject via `Crypto().Decrypt` (opaque, `tokenID:subject`) or `VerifyAccessToken` (JWT). Missing/invalid tokens → 401 `access token missing` / `access token invalid`; storage errors → 403; success → JSON `oidc.UserInfo` filled by `Storage.SetUserinfoFromToken` (with the `Origin` header).

### Method
GET

### Endpoint
/userinfo

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **sub** (string) - Subject identifier
- **name** (string) - User's full name
- **given_name** (string) - User's given name
- **family_name** (string) - User's family name
- **preferred_username** (string) - Preferred username
- **email** (string) - Email address
- **email_verified** (boolean) - Email verification status

#### Response Example
{
  "sub": "string",
  "name": "string",
  "given_name": "string",
  "family_name": "string",
  "preferred_username": "string",
  "email": "string",
  "email_verified": true
}

### Error Handling
- **401** - `access token missing` or `access token invalid`
- **403** - Storage error
```

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

### WithPrompt

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

Option constructor for adding a prompt parameter to the authorization URL.

```APIDOC
## WithPrompt

### Description
Option constructor for adding a prompt parameter to the authorization URL.

### Function Signature
func WithPrompt(prompt ...string) AuthURLOpt

### Parameters
- **prompt** (string) - Required - The prompt values.

### Returns
- **AuthURLOpt** - The option.
```

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

### Key Binding Option

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

Experimental option to enable DPoP key binding. Requires OpenID Connect, validates key strength, rejects nil signers and mismatches, appends the `bound_key` scope, and registers a DPoP proof signer.

```go
func WithKeyBinding(signer crypto.Signer, alg jose.SignatureAlgorithm) Option
```

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

### Userinfo: SubjectGetter interface, callback type, and Userinfo function

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

Defines the SubjectGetter interface and the CodeExchangeUserinfoCallback type, plus the UserinfoCallback and Userinfo functions. Userinfo GETs the userinfo endpoint with Authorization: <tokenType> <token> and checks that userinfo.GetSubject() equals the provided subject, returning ErrUserInfoSubNotMatching on mismatch.

```go
type SubjectGetter interface {
	GetSubject() string
}

type CodeExchangeUserinfoCallback[C oidc.IDClaims, U SubjectGetter] func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens[C], state string, provider RelyingParty, info U)

func UserinfoCallback[C oidc.IDClaims, U SubjectGetter](f CodeExchangeUserinfoCallback[C, U]) CodeExchangeCallback[C]
func Userinfo[U SubjectGetter](ctx context.Context, token, tokenType, subject string, rp RelyingParty) (userinfo U, err error)
```

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

### Options for TokenExchanger

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

Options to customize the HTTP client and static token endpoint. Discovery is used unless a static endpoint is given.

```go
func WithHTTPClient(client *http.Client) func(*OAuthTokenExchange)
func WithStaticTokenEndpoint(issuer, tokenEndpoint string) func(*OAuthTokenExchange)
```

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

### Introspector interfaces and functions (token_introspection.go)

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-token.md

Defines the Introspector and IntrospectorJWTProfile interfaces, plus the Introspect and ParseTokenIntrospectionRequest functions. Client authentication is required; unauthenticated requests return oidc.ErrInvalidClient().WithParent(ErrNoClientCredentials). Unknown or invalid tokens produce {"active": false}; active tokens get SetIntrospectionFromToken and active: true.

```go
type Introspector interface {
	Decoder() httphelper.Decoder
	Crypto() Crypto
	Storage() Storage
	AccessTokenVerifier(context.Context) *AccessTokenVerifier
}

type IntrospectorJWTProfile interface {
	Introspector
	JWTProfileVerifier(context.Context) JWTProfileVerifier
}

func Introspect(w http.ResponseWriter, r *http.Request, introspector Introspector)
func ParseTokenIntrospectionRequest(r *http.Request, introspector Introspector) (token, clientID string, err error)

type IntrospectionRequest struct {
	*ClientCredentials
	*oidc.IntrospectionRequest
}
```

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

### WithPromptURLParam

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

Option constructor for adding a prompt parameter to the authorization URL.

```APIDOC
## WithPromptURLParam

### Description
Option constructor for adding a prompt parameter to the authorization URL.

### Function Signature
func WithPromptURLParam(prompt ...string) URLParamOpt

### Parameters
- **prompt** (string) - Required - The prompt values.

### Returns
- **URLParamOpt** - The option.
```

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

### Run local OpenTelemetry-k6 compatibility check

Source: https://github.com/zitadel/oidc/blob/main/CONTRIBUTING.md

Executes the same check as the CI 'otel not ahead of k6' workflow. It compares the required otel versions with the latest k6 release. Set K6_VERSION to check against a specific k6 tag.

```bash
.github/scripts/check-otel-k6-compat.sh
```

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

### CreateDiscoveryConfig

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-endpoints.md

Builds the discovery configuration from a Configuration and DiscoverStorage.

```APIDOC
## [FUNCTION] CreateDiscoveryConfig

### Description
Builds the `oidc.DiscoveryConfiguration` from a `Configuration` and `DiscoverStorage`.

### Function Signature
```go
func CreateDiscoveryConfig(ctx context.Context, config Configuration, storage DiscoverStorage) *oidc.DiscoveryConfiguration
```

### Parameters
- **ctx** (context.Context) - Required - The context, used to obtain the issuer.
- **config** (Configuration) - Required - The server configuration.
- **storage** (DiscoverStorage) - Required - The storage interface providing signature algorithms.

### Returns
- **\*oidc.DiscoveryConfiguration** - The generated discovery configuration.

```

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

### Constructors for TokenExchanger

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

Provides three constructors for creating a TokenExchanger: with no auth, with client credentials, and with JWT profile.

```go
func NewTokenExchanger(ctx context.Context, issuer string, options ...func(source *OAuthTokenExchange)) (TokenExchanger, error)
func NewTokenExchangerClientCredentials(ctx context.Context, issuer, clientID, clientSecret string, options ...func(source *OAuthTokenExchange)) (TokenExchanger, error)
func NewTokenExchangerJWTProfile(ctx context.Context, issuer, clientID string, signer jose.Signer, options ...func(source *OAuthTokenExchange)) (TokenExchanger, error)
```

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

### NewLegacyServer

Source: https://github.com/zitadel/oidc/blob/main/_autodocs/api-reference/op-server.md

Creates a new LegacyServer instance with the given provider and endpoints.

```APIDOC
## NewLegacyServer

### Description
Constructs a LegacyServer that adapts a classic OpenIDProvider to the Server interface, delegating every endpoint to the provider/storage.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **provider** (OpenIDProvider) - Required - The OpenID provider to adapt.
- **endpoints** (Endpoints) - Required - The endpoints to register; nil endpoints are disabled.

### Request Example
N/A

### Response
#### Success Response
- **server** (*LegacyServer) - The new LegacyServer instance.

#### Response Example
N/A
```
Tokens:
Raw