Tencent/WeKnora · error

missing external user token

Error message

missing external user token

What it means

Ad-hoc error created in verifyExternalUserJWT (called from resolveAPIPrincipal) when the X-External-User-Token header value is empty after trimming. It is an input guard: no token was supplied, so JWT parsing is skipped entirely.

Source

Thrown at internal/middleware/auth.go:615

			return types.Principal{}, fmt.Errorf("%w: %w", errInvalidExternalUserToken, err)
		}
		if err := validateExternalUserID(externalUserID); err != nil {
			return types.Principal{}, fmt.Errorf("%w: %v", errInvalidExternalUserID, err)
		}
		return types.Principal{
			Type: types.PrincipalAPIExternalUser,
			ID:   strconv.FormatUint(tenantID, 10) + ":" + externalUserID,
		}, nil
	default:
		return fallback, nil
	}
}

func verifyExternalUserJWT(tokenString string, tenantID uint64, secret string) (string, error) {
	tokenString = strings.TrimSpace(tokenString)
	secret = strings.TrimSpace(secret)
	if tokenString == "" {
		return "", errors.New("missing external user token")
	}
	if secret == "" {
		return "", errors.New("external user token secret is not configured")
	}
	claims := jwt.MapClaims{}
	parser := jwt.NewParser(
		jwt.WithAudience("weknora"),
		jwt.WithExpirationRequired(),
		jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
	)
	token, err := parser.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
		}
		return []byte(secret), nil
	})
	if err != nil {
		return "", err

View on GitHub (pinned to 988cbb0330)

Solutions

1. Client must provide the X-External-User-Token header alongside X-External-User-ID
2. If tokens are optional for this deployment, adjust the auth mode so the fallback principal applies
3. Trim whitespace client-side; an all-whitespace header counts as missing

When it happens

Trigger: Thrown at internal/middleware/auth.go:615 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/0e7802f03031a284. Report an issue: GitHub.