jentz · remcojansen · May 20, 2026 · May 10, 2026
diff --git a/EXAMPLES.md b/EXAMPLES.md
@@ -42,9 +42,9 @@ Run a regular authorization code flow (with or without PKCE)
 oidc-cli authorization_code [--pkce]
 ```
 
-Adding custom ```scopes```
+Adding custom ```scope```
 ```sh
-oidc-cli authorization_code --scopes "<scope1 scope2 scopeN>"
+oidc-cli authorization_code --scope "<scope1 scope2 scopeN>"
 ```
 
 Providing custom ```acr_values```
@@ -57,7 +57,7 @@ oidc-cli authorization_code --acr-values "<acr>"
 Run a client credentials flow.
 
 ```sh
-oidc-cli client_credentials [--scopes "<scope1 scope2 scopeN>"]
+oidc-cli client_credentials [--scope "<scope1 scope2 scopeN>"]
 ```
 
 ## Check validity and content of access token

diff --git a/README.md b/README.md
@@ -54,7 +54,7 @@ You can also download a suitable release for your platform from the [releases pa
 ## Run ▶️
 
 ```bash
-go run ./ authorization_code --authorization-url <authorization-url> --token-url <token-url> --client-id <client-id> --client-secret <client-secret> --scopes "openid profile"
+go run ./ authorization_code --authorization-url <authorization-url> --token-url <token-url> --client-id <client-id> --client-secret <client-secret> --scope "openid profile"
 ```
 
 ## Test

diff --git a/cmd/authorization_code_cfg.go b/cmd/authorization_code_cfg.go
@@ -38,7 +38,7 @@ func parseAuthorizationCodeFlags(in ParseInput) (runner CommandRunner, output st
 	flags.StringVar(&oidcConf.DPoPPublicKeyFile, "dpop-public-key", "", "file to read public key from (eg. for DPoP)")
 
 	var flowConf oidc.AuthorizationCodeFlowConfig
-	flags.StringVar(&flowConf.Scopes, "scopes", "openid", "set scopes as a space separated list")
+	flags.StringVar(&flowConf.Scope, "scope", "openid", "set scope as a space separated list")
 	flags.StringVar(&flowConf.CallbackURI, "callback-uri", "http://localhost:9555/callback",
 		"set callback uri (default: http://localhost:9555/callback), this will also be used as the redirect_uri in the authorization request unless overridden by -redirect-uri")
 	flags.StringVar(&flowConf.RedirectURI, "redirect-uri", "", "set the redirect_uri parameter")
@@ -93,8 +93,8 @@ func parseAuthorizationCodeFlags(in ParseInput) (runner CommandRunner, output st
 			"client-secret is required unless using PKCE",
 		},
 		{
-			flowConf.Scopes == "",
-			"scopes are required",
+			flowConf.Scope == "",
+			"scope is required",
 		},
 		{
 			flowConf.CallbackURI == "",

diff --git a/cmd/authorization_code_cfg_test.go b/cmd/authorization_code_cfg_test.go
@@ -27,7 +27,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--skip-tls-verify",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 				"--prompt", "login",
 				"--acr-values", "acr_values",
@@ -55,7 +55,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				DPoPPublicKeyFile:     "path/to/public-key.pem",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:8080/callback",
 				Prompt:      "login",
 				AcrValues:   "acr_values",
@@ -78,7 +78,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 			},
 			oidc.Config{
@@ -90,15 +90,15 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:8080/callback",
 				PKCE:        false,
 				PAR:         false,
 				DPoP:        false,
 			},
 		},
 		{
-			"no scopes provided",
+			"no scope provided",
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
@@ -114,7 +114,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid",
+				Scope:       "openid",
 				CallbackURI: "http://localhost:8080/callback",
 				PKCE:        false,
 				PAR:         false,
@@ -127,7 +127,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 			},
 			oidc.Config{
 				IssuerURL:             "https://example.com",
@@ -138,7 +138,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:9555/callback",
 				PKCE:        false,
 				PAR:         false,
@@ -151,7 +151,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--pkce",
 			},
 			oidc.Config{
@@ -163,7 +163,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:9555/callback",
 				PKCE:        true,
 				PAR:         false,
@@ -175,7 +175,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--pkce",
 			},
 			oidc.Config{
@@ -187,7 +187,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:9555/callback",
 				PKCE:        true,
 				PAR:         false,
@@ -200,7 +200,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--dpop",
 				"--dpop-private-key", "path/to/private-key.pem",
 				"--dpop-public-key", "path/to/public-key.pem",
@@ -216,7 +216,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				DPoPPublicKeyFile:     "path/to/public-key.pem",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid profile email",
+				Scope:       "openid profile email",
 				CallbackURI: "http://localhost:9555/callback",
 				PKCE:        false,
 				PAR:         false,
@@ -230,7 +230,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
 				"non-flag-argument",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 			},
 			oidc.Config{
@@ -242,7 +242,7 @@ func TestParseAuthorizationCodeFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.AuthorizationCodeFlowConfig{
-				Scopes:      "openid",                         // expecting default value as argument is not parsed
+				Scope:       "openid",                         // expecting default value as argument is not parsed
 				CallbackURI: "http://localhost:9555/callback", // expecting default value as argument is not parsed
 				PKCE:        false,
 				PAR:         false,
@@ -286,7 +286,7 @@ func TestParseAuthorizationCodeFlagsError(t *testing.T) {
 			[]string{
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 			},
 		},
@@ -295,7 +295,7 @@ func TestParseAuthorizationCodeFlagsError(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 			},
 		},
@@ -304,7 +304,7 @@ func TestParseAuthorizationCodeFlagsError(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 				"--dpop",
 				"--dpop-public-key", "path/to/public-key.pem",
@@ -315,7 +315,7 @@ func TestParseAuthorizationCodeFlagsError(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--callback-uri", "http://localhost:8080/callback",
 				"--dpop",
 				"--dpop-private-key", "path/to/private-key.pem",

diff --git a/cmd/client_credentials_cfg.go b/cmd/client_credentials_cfg.go
@@ -22,7 +22,7 @@ func parseClientCredentialsFlags(in ParseInput) (runner CommandRunner, output st
 	flags.Var(&oidcConf.AuthMethod, "auth-method", "auth method to use (client_secret_basic or client_secret_post)")
 
 	var flowConf oidc.ClientCredentialsFlowConfig
-	flags.StringVar(&flowConf.Scopes, "scopes", "", "set scopes as a space separated list")
+	flags.StringVar(&flowConf.Scope, "scope", "", "set scope as a space separated list")
 
 	runner = &oidc.ClientCredentialsFlow{
 		Config:     oidcConf,

diff --git a/cmd/client_credentials_cfg_test.go b/cmd/client_credentials_cfg_test.go
@@ -33,7 +33,7 @@ func TestParseClientCredentialsFlagsResult(t *testing.T) {
 				ClientSecret:      "client-secret",
 			},
 			oidc.ClientCredentialsFlowConfig{
-				Scopes: "",
+				Scope: "",
 			},
 		},
 		{
@@ -52,16 +52,16 @@ func TestParseClientCredentialsFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.ClientCredentialsFlowConfig{
-				Scopes: "",
+				Scope: "",
 			},
 		},
 		{
-			"scopes provided",
+			"scope provided",
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
-				"--scopes", "expected",
+				"--scope", "expected",
 			},
 			oidc.Config{
 				IssuerURL:             "https://example.com",
@@ -72,7 +72,7 @@ func TestParseClientCredentialsFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.ClientCredentialsFlowConfig{
-				Scopes: "expected",
+				Scope: "expected",
 			},
 		},
 	}

diff --git a/cmd/token_refresh_cfg.go b/cmd/token_refresh_cfg.go
@@ -25,7 +25,7 @@ func parseTokenRefreshFlags(in ParseInput) (runner CommandRunner, output string,
 
 	var flowConf oidc.TokenRefreshFlowConfig
 	flags.StringVar(&flowConf.RefreshToken, "refresh-token", "", "refresh token to be used for token refresh")
-	flags.StringVar(&flowConf.Scopes, "scopes", "", "set scopes as a space separated list")
+	flags.StringVar(&flowConf.Scope, "scope", "", "set scope as a space separated list")
 	flags.BoolVar(&flowConf.DPoP, "dpop", false, "use dpop-bound refresh tokens")
 
 	runner = &oidc.TokenRefreshFlow{

diff --git a/cmd/token_refresh_cfg_test.go b/cmd/token_refresh_cfg_test.go
@@ -26,7 +26,7 @@ func TestParseTokenRefreshFlagsResult(t *testing.T) {
 				"--client-id", "client-id",
 				"--client-secret", "client-secret",
 				"--refresh-token", "refresh-token",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 			},
 			oidc.Config{
 				IssuerURL:             "https://example.com",
@@ -36,13 +36,13 @@ func TestParseTokenRefreshFlagsResult(t *testing.T) {
 				ClientSecret:          "client-secret",
 			},
 			oidc.TokenRefreshFlowConfig{
-				Scopes:       "openid profile email",
+				Scope:        "openid profile email",
 				RefreshToken: "refresh-token",
 				DPoP:         false,
 			},
 		},
 		{
-			"only issuer, no scopes",
+			"only issuer, no scope",
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
@@ -158,7 +158,7 @@ func TestParseTokenRefreshFlagsError(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--refresh-token", "refresh-token",
 				"--dpop",
 				"--dpop-public-key", "path/to/public-key.pem",
@@ -170,7 +170,7 @@ func TestParseTokenRefreshFlagsError(t *testing.T) {
 			[]string{
 				"--issuer", "https://example.com",
 				"--client-id", "client-id",
-				"--scopes", "openid profile email",
+				"--scope", "openid profile email",
 				"--refresh-token", "refresh-token",
 				"--dpop",
 				"--dpop-private-key", "path/to/private-key.pem",

diff --git a/oidc/authorization_code.go b/oidc/authorization_code.go
@@ -15,7 +15,7 @@ type AuthorizationCodeFlow struct {
 }
 
 type AuthorizationCodeFlowConfig struct {
-	Scopes      string
+	Scope       string
 	CallbackURI string
 	RedirectURI string
 	Prompt      string
@@ -47,7 +47,7 @@ func (c *AuthorizationCodeFlow) setupPKCE() (string, error) {
 func (c *AuthorizationCodeFlow) createAuthCodeRequest(ctx context.Context, codeVerifier string) (*httpclient.AuthorizationCodeRequest, error) {
 	req := &httpclient.AuthorizationCodeRequest{
 		ClientID:    c.Config.ClientID,
-		Scope:       c.FlowConfig.Scopes,
+		Scope:       c.FlowConfig.Scope,
 		RedirectURI: c.FlowConfig.RedirectURI,
 		Prompt:      c.FlowConfig.Prompt,
 		AcrValues:   c.FlowConfig.AcrValues,

diff --git a/oidc/client_credentials.go b/oidc/client_credentials.go
@@ -14,7 +14,7 @@ type ClientCredentialsFlow struct {
 }
 
 type ClientCredentialsFlowConfig struct {
-	Scopes string
+	Scope string
 }
 
 func (c *ClientCredentialsFlow) Run(ctx context.Context) error {
@@ -24,7 +24,7 @@ func (c *ClientCredentialsFlow) Run(ctx context.Context) error {
 		c.Config.ClientID,
 		c.Config.ClientSecret,
 		c.Config.AuthMethod,
-		c.FlowConfig.Scopes,
+		c.FlowConfig.Scope,
 	)
 
 	resp, err := client.ExecuteTokenRequest(ctx, c.Config.TokenEndpoint, req)

diff --git a/oidc/token_refresh.go b/oidc/token_refresh.go
@@ -15,15 +15,15 @@ type TokenRefreshFlow struct {
 }
 
 type TokenRefreshFlowConfig struct {
-	Scopes       string
+	Scope        string
 	RefreshToken string
 	DPoP         bool
 }
 
 func (c *TokenRefreshFlow) Run(ctx context.Context) error {
 	client := c.Config.Client
 
-	req := httpclient.CreateRefreshTokenRequest(c.Config.ClientID, c.Config.ClientSecret, c.Config.AuthMethod, c.FlowConfig.RefreshToken, c.FlowConfig.Scopes)
+	req := httpclient.CreateRefreshTokenRequest(c.Config.ClientID, c.Config.ClientSecret, c.Config.AuthMethod, c.FlowConfig.RefreshToken, c.FlowConfig.Scope)
 
 	// Handle DPoP
 	if c.FlowConfig.DPoP {
-Original file line number
+Diff line change
@@ Expand Up @@
     ## Run ▶️
     ```bash
-    go run ./ authorization_code --authorization-url <authorization-url> --token-url <token-url> --client-id <client-id> --client-secret <client-secret> --scopes "openid profile"
+    go run ./ authorization_code --authorization-url <authorization-url> --token-url <token-url> --client-id <client-id> --client-secret <client-secret> --scope "openid profile"
     ```
     ## Test
@@ Expand Down @@