ory/kratos · error

api_key auth strategy requires a string name

Error message

api_key auth strategy requires a string name

What it means

authStrategy constructs the HTTP auth strategy for a webhook caller from a generic map. For type "api_key" it requires a string "name" field (the header/query parameter name); if config["name"] is absent or not a string, builder creation fails with this error.

Solutions

1. Add a string "name" field to the api_key auth config
2. Quote the name value in YAML so it stays a string
3. Set "name" to the header (or query param) name, e.g. "X-Api-Key"
4. Also verify "value" is a string, since the next check will fail otherwise

Example fix

// before
auth: {type: api_key, value: secret123}
// after
auth: {type: api_key, name: X-Api-Key, value: secret123}

// Go: check api_key auth config before building
func validateAPIKeyAuth(cfg map[string]interface{}) error {
	if _, ok := cfg["name"].(string); !ok {
		return errors.New("api_key auth requires a string name")
	}
	if _, ok := cfg["value"].(string); !ok {
		return errors.New("api_key auth requires a string value")
	}
	return nil
}

func hasAPIKeyName(cfg map[string]interface{}) bool {
	_, ok := cfg["name"].(string)
	return ok
}

b, err := request.NewBuilder(cfg)
if err != nil {
	if strings.Contains(err.Error(), "requires a string name") {
		return fmt.Errorf("webhook api_key auth: add a string 'name' (header/param name) to config")
	}
	return err
}

When it happens

Trigger: Webhook auth config {"type": "api_key"} with no "name" key, or "name" set to a non-string (number, bool, object, null), passed into NewBuilder's request config.

Common situations: YAML config where the header name is unquoted and parsed as a number (e.g. name: 123); forgetting the name key; copying a basic_auth config but switching type to api_key without adding name/value.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• api_key auth strategy requires a string value
• basic_auth auth strategy requires a string user
• basic_auth auth strategy requires a string password
• no credentials found
• failed to unmarshal webhook configuration for

AI-assisted analysis of ory/kratos@b86338da04 (2026-09-07). Data as JSON: /api/errors/d0cd8da4f11a527d. Report an issue: GitHub.

Appendix: source

Thrown at request/auth.go:36

	}
	apiKeyStrategy struct {
		name  string
		value string
		in    string
	}
	AuthStrategy interface {
		apply(req *retryablehttp.Request)
	}
)

func authStrategy(typ string, config map[string]any) (AuthStrategy, error) {
	switch typ {
	case "":
		return NewNoopAuthStrategy(), nil
	case "api_key":
		name, ok := config["name"].(string)
		if !ok {
			return nil, fmt.Errorf("api_key auth strategy requires a string name")
		}
		value, ok := config["value"].(string)
		if !ok {
			return nil, fmt.Errorf("api_key auth strategy requires a string value")
		}
		in, _ := config["in"].(string) // in is optional
		return NewAPIKeyStrategy(in, name, value), nil
	case "basic_auth":
		user, ok := config["user"].(string)
		if !ok {
			return nil, fmt.Errorf("basic_auth auth strategy requires a string user")
		}
		password, ok := config["password"].(string)
		if !ok {
			return nil, fmt.Errorf("basic_auth auth strategy requires a string password")
		}
		return NewBasicAuthStrategy(user, password), nil
	}

View on GitHub (pinned to b86338da04)