Processor

Processor is the core JWT operation type, implementing the TokenManager interface. All methods are concurrency-safe.

Create an instance via jwt.New(cfg).

Create

func (p *Processor) Create(claims CustomClaims) (string, error)

Creates a new JWT access token. Accepts any type implementing the CustomClaims interface.

Parameters

Parameter	Type	Description
claims	CustomClaims	Token claims

Returns

Return	Type	Description
token	string	Signed JWT string
err	error	Error on validation or signing failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrInvalidClaims	Claims validation failed
ErrRateLimitExceeded	Rate limit threshold exceeded

Example

// Built-in Claims
claims := &jwt.Claims{UserID: "user123", Username: "alice"}
token, err := processor.Create(claims)

// Custom Claims
myClaims := &MyClaims{UserID: "123"}
token, err := processor.Create(myClaims)

---

Parse v1.2.3+

func (p *Processor) Parse(tokenString string) (Claims, error)

Validates a JWT access token and returns the parsed Claims (value copy). A nil err means the token is valid — there is no separate boolean to check. Replaces the deprecated Validate.

Parameters

Parameter	Type	Description
tokenString	string	JWT string

Returns

Return	Type	Description
claims	Claims	Parsed claims (value copy)
err	error	Error on validation failure; nil means valid

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed
ErrTokenTypeMismatch	Token has type refresh and RejectRefreshAsAccess is enabled

Example

claims, err := processor.Parse(tokenString)
if err != nil {
    // Handle error
    return
}
fmt.Println(claims.UserID)

---

Validate

func (p *Processor) Validate(tokenString string) (Claims, bool, error)

Deprecated

Validate is deprecated since v1.2.3: the boolean result valid is always equivalent to err == nil and carries no extra information. Use Parse, which returns (Claims, error).

Validates a JWT access token and returns the parsed Claims. Internally delegates directly to Parse.

Migrating from Validate to Parse

valid is always equivalent to err == nil — migrating is just dropping the boolean check:

// Old style (deprecated)
parsed, valid, err := processor.Validate(token)
if valid {
    // ...
}

// New style: nil err means valid
parsed, err := processor.Parse(token)
if err != nil {
    // Handle error
}

Parameters

Parameter	Type	Description
tokenString	string	JWT string

Returns

Return	Type	Description
claims	Claims	Parsed claims (value copy)
valid	bool	Whether valid (always equal to err == nil)
err	error	Error on validation failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed
ErrTokenTypeMismatch	Token has type refresh and RejectRefreshAsAccess is enabled

Example

claims, valid, err := processor.Validate(tokenString)
if err != nil {
    // Handle error
    return
}
if valid {
    fmt.Println(claims.UserID)
}

---

CreateRefresh

func (p *Processor) CreateRefresh(claims CustomClaims) (string, error)

Creates a refresh token using RefreshTokenTTL instead of AccessTokenTTL.

Parameters

Parameter	Type	Description
claims	CustomClaims	Token claims

Returns

Return	Type	Description
token	string	Signed refresh token
err	error	Error on validation or signing failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrInvalidClaims	Claims validation failed
ErrRateLimitExceeded	Rate limit threshold exceeded

---

Refresh

func (p *Processor) Refresh(refreshTokenString string) (string, error)

Refreshes an existing refresh token and returns a new access token. The refresh token is fully validated (signature, expiration, blacklist) before a new access token is issued; the original token's IssuedAt, ExpiresAt, and ID are reset and regenerated.

Token Type & Rotation

• Token type check: Tokens with token_type=access are rejected (returns ErrTokenTypeMismatch) to prevent access tokens from being used to obtain new tokens; older tokens without a token_type are still accepted for backward compatibility.
• Does not auto-revoke the original token by default: Refresh does not revoke the supplied refresh token by default. The original token remains valid until it expires or is explicitly Revoke()d. For one-time-use semantics, enable Config.RotateRefreshTokens (since v1.2.3; revocation happens before the new token is minted — see Token Refresh & Rotation); manually calling Revoke(refreshTokenString) after a successful Refresh is an equivalent alternative.

Security Note

Refresh only validates standard JWT fields (exp, nbf, iss, aud, blacklist) and basic structural validity (UserID or Username must exist). Deep field constraints (length limits, injection patterns) are not re-checked since they were validated at creation time.

Parameters

Parameter	Type	Description
refreshTokenString	string	Refresh token

Returns

Return	Type	Description
token	string	New access token
err	error	Error on validation failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed
ErrTokenTypeMismatch	Refreshing with an access token (token_type=access)
ErrTokenMissingID	RotateRefreshTokens is enabled but the refresh token lacks a jti claim
ErrBlacklistNotConfigured	RotateRefreshTokens is enabled but the blacklist is not configured
ErrRefreshRotationFailed	Revoking the old refresh token failed while RotateRefreshTokens is enabled (wraps the underlying store error)
ErrRateLimitExceeded	Rate limit threshold exceeded

---

ParseInto v1.2.3+

func (p *Processor) ParseInto(tokenString string, claims CustomClaims) (CustomClaims, error)

Verifies a token and populates the provided custom Claims struct in place; on success it returns the same pointer that was passed in. A nil err means the token is valid. Unlike Parse, which returns a value copy, this fills the caller-supplied struct directly.

Claims state on error

On validation failure the supplied claims may be partially populated and must not be used.

Parameters

Parameter	Type	Description
tokenString	string	JWT string
claims	CustomClaims	Target Claims pointer

Returns

Return	Type	Description
claims	CustomClaims	Populated Claims (same pointer as the input)
err	error	Error on validation failure; nil means valid

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed
ErrTokenTypeMismatch	Token has type refresh and RejectRefreshAsAccess is enabled

Example

myClaims := &MyClaims{}
result, err := processor.ParseInto(tokenString, myClaims)
if err != nil {
    // Handle error
    return
}
fmt.Println(result.(*MyClaims).UserID)

---

ValidateInto

func (p *Processor) ValidateInto(tokenString string, claims CustomClaims) (CustomClaims, bool, error)

Deprecated

ValidateInto is deprecated since v1.2.3: the boolean result valid is always equivalent to err == nil. Use ParseInto, which returns (CustomClaims, error); the migration is identical to Validate → Parse.

Validates a token and populates a custom Claims struct. Returns the same pointer as the input claims.

Parameters

Parameter	Type	Description
tokenString	string	JWT string
claims	CustomClaims	Target Claims pointer

Returns

Return	Type	Description
claims	CustomClaims	Populated Claims
valid	bool	Whether valid (always equal to err == nil)
err	error	Error on validation failure

Example

myClaims := &MyClaims{}
result, valid, err := processor.ValidateInto(tokenString, myClaims)
if valid {
    fmt.Println(result.(*MyClaims).UserID)
}

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed

---

RefreshInto

func (p *Processor) RefreshInto(refreshTokenString string, claims CustomClaims) (string, error)

Refreshes a token using custom Claims. Timing fields (IssuedAt, ExpiresAt, ID) are automatically restored after the operation, even if an error or panic occurs.

Token Type Check

Tokens with token_type=access are rejected (returns ErrTokenTypeMismatch) to prevent access tokens from being used to obtain new tokens; older tokens without a token_type are still accepted for backward compatibility.

Security Note

Refresh only validates standard JWT fields and basic structural validity. Deep field constraints are not re-checked since they were validated at creation time.

Parameters

Parameter	Type	Description
refreshTokenString	string	Refresh token
claims	CustomClaims	Target Claims pointer

Returns

Return	Type	Description
token	string	New access token
err	error	Error on validation failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature
ErrAlgorithmMismatch	Token algorithm does not match config
ErrExpirationRequired	RequireExpiration is enabled but the token lacks an exp claim
ErrTokenExpired	Token expired
ErrTokenNotValidYet	Token not yet valid
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenRevoked	Token revoked
ErrInvalidClaims	Claims validation failed
ErrTokenTypeMismatch	Refreshing with an access token (token_type=access)
ErrTokenMissingID	RotateRefreshTokens is enabled but the refresh token lacks a jti claim
ErrBlacklistNotConfigured	RotateRefreshTokens is enabled but the blacklist is not configured
ErrRefreshRotationFailed	Revoking the old refresh token failed while RotateRefreshTokens is enabled (wraps the underlying store error)
ErrRateLimitExceeded	Rate limit threshold exceeded

---

Revoke

func (p *Processor) Revoke(tokenString string) error

Adds the token to the blacklist by verifying the signature and extracting the token ID (jti). Only tokens with a valid signature can be revoked, preventing malicious callers from adding arbitrary token IDs to the blacklist.

TTL Behavior

• The token's exp determines the TTL of the blacklist entry
• Tokens without an exp default to a 7-day TTL
• TTL is capped at 30 days to prevent forged excessive exp values from locking memory (DoS protection)
• Expired tokens can still be revoked; the entry is automatically cleaned up by the blacklist

Parameters

Parameter	Type	Description
tokenString	string	Token to revoke

Returns

Return	Type	Description
err	error	Error on revocation failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrBlacklistNotConfigured	Blacklist not configured
ErrInvalidToken	Invalid signature or malformed token
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenMissingID	Token missing jti field

---

IsRevoked

func (p *Processor) IsRevoked(tokenString string) (bool, error)

Checks whether a token has been revoked. After verifying the signature, it looks up the token's jti status in the blacklist. When the blacklist is not configured, returns false and a nil error.

Parameters

Parameter	Type	Description
tokenString	string	JWT string

Returns

Return	Type	Description
revoked	bool	Whether revoked
err	error	Error on query failure

Errors

Error	Trigger Condition
ErrProcessorClosed	Processor is closed
ErrEmptyToken	Token is empty
ErrInvalidToken	Invalid signature or malformed token
ErrTokenInvalidIssuer	Issuer mismatch
ErrTokenInvalidAudience	Audience mismatch
ErrTokenMissingID	Token missing jti field

---

ParseUnverified

func (p *Processor) ParseUnverified(tokenString string, claims any) error

Parses a token without verifying the signature. Useful for extracting Claims information without needing to trust the token.

DANGER

The returned Claims are not verified and must not be trusted. Only use for debugging or logging.

Parameters

Parameter	Type	Description
tokenString	string	JWT string
claims	any	Target Claims pointer

Returns

Return	Type	Description
err	error	Error on parse failure

Errors

Error	Condition
ErrProcessorClosed	Processor has been closed
ErrEmptyToken	Token is empty
Wrapped error	Returns a wrapped parse error on malformed tokens (not a sentinel error; cannot be matched with errors.Is)

---

Close

func (p *Processor) Close() error

Releases resources and securely clears keys. Can be called multiple times; subsequent calls return ErrProcessorClosed.

Returns

Return	Type	Description
err	error	Error on close failure

---

IsClosed

func (p *Processor) IsClosed() bool

Checks if the Processor is closed.

Returns

Return	Type	Description
closed	bool	Whether closed