Tencent/WeKnora · error

invalid external user token

Error message

invalid external user token

What it means

Sentinel returned by resolveAPIPrincipal when the X-External-User-Token fails JWT verification (verifyExternalUserJWT) or yields no user id, and also re-embedded by verifyExternalUserJWT's own invalid-token path. Rendered as 'Unauthorized: invalid external user token'; the wrapped cause distinguishes signature, expiry, or format problems.

Source

Thrown at internal/middleware/auth.go:32

	"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"},
	"/api/v1/auth/oidc/config":        {"GET"},

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check that the JWT is signed with the tenant's configured external-user-token secret (HS256)
2. Verify the token has not expired and includes the required claims (exp, audience 'weknora')
3. Re-issue the token if the signing secret was rotated
4. Inspect the wrapped inner error for the precise verification failure

When it happens

Trigger: Thrown at internal/middleware/auth.go:32 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/5fbe26d9cba06205. Report an issue: GitHub.