Tencent/WeKnora · error

invalid external user id

Error message

invalid external user id

What it means

Sentinel returned by resolveAPIPrincipal when validateExternalUserID rejects the value from the X-External-User-ID header (e.g. empty after trim, exceeds maxExternalUserIDLen=128, or contains invalid characters). Wrapped with the validation detail and rendered as 'Unauthorized: invalid external user id'.

Source

Thrown at internal/middleware/auth.go:31

	"github.com/Tencent/WeKnora/internal/config"
	"github.com/Tencent/WeKnora/internal/logger"
	"github.com/Tencent/WeKnora/internal/types"
	"github.com/Tencent/WeKnora/internal/types/interfaces"
	"github.com/gin-gonic/gin"
	"github.com/golang-jwt/jwt/v5"
)

const (
	defaultExternalUserIDHeader    = "X-External-User-ID"
	defaultExternalUserTokenHeader = "X-External-User-Token"
	maxExternalUserIDLen           = 128
	maxExternalUserTokenTTL        = 24 * time.Hour
)

var (
	errMissingDirectHeader      = errors.New("missing external user id header")
	errInvalidExternalUserID    = errors.New("invalid external user id")
	errInvalidExternalUserToken = errors.New("invalid external user token")
)

// 无需认证的API列表
var noAuthAPI = map[string][]string{
	"/health":                 {"GET"},
	"/api/v1/auth/register":   {"POST"},
	"/api/v1/auth/login":      {"POST"},
	"/api/v1/auth/auto-setup": {"POST"},
	// Share-link surfaces accept a plaintext invite token from anonymous
	// callers (an invitee who hasn't registered yet). They are registered
	// as public routes in RegisterAuthRoutes and rate-limited by IP, so the
	// global Auth middleware must let them through — otherwise opening a
	// share link while logged out 401s and the frontend bounces the user to
	// /login instead of the register page (issue #1617).
	"/api/v1/auth/invitations/lookup": {"POST"},
	"/api/v1/auth/register-by-invite": {"POST"},
	"/api/v1/auth/config":             {"GET"},

View on GitHub (pinned to 988cbb0330)

Solutions

1. Ensure the external user id is non-empty, at most 128 chars, and uses allowed characters
2. Log the wrapped validation detail to see which rule failed
3. Sanitize/trim the header value on the client before sending

When it happens

Trigger: Thrown at internal/middleware/auth.go:31 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/b678647c69674aac. Report an issue: GitHub.