jwt_sign_hs256

Sign a JSON claims object as a JWT (JSON Web Token) using the HS256 (HMAC-SHA256) algorithm. Useful for generating test tokens, building auth payloads for downstream API calls, or producing tokens in CI pipelines without a running auth service.

Parameters

Parameter	Type	Required	Description
payload	object	Yes	JSON claims object to encode. Must be a JSON object (not an array or primitive). Standard claims (exp, iat, sub) are not added automatically — include them in payload if needed.
secret	string	Yes	HMAC shared secret used to sign the token.

Response

Field	Type	Description
token	string	The newly signed JWT string.

Example

{
	"payload": {
		"sub": "user_42",
		"role": "admin",
		"exp": 9999999999
	},
	"secret": "my-shared-secret"
}

Result:

{
	"token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyXzQyIiwicm9sZSI6ImFkbWluIiwiZXhwIjo5OTk5OTk5OTk5fQ.Jg..."
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	The payload or secret argument is missing or the wrong type.	protocol error (invalid_params)
jwt_payload_not_object	payload is valid JSON but not a JSON object (arrays and primitives are rejected).	tool error (isError)
jwt_sign_failed	The token could not be signed with the given secret.	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• Claims are not added automatically. If you need exp, iat, nbf, or sub, include them explicitly in payload.
• Only symmetric (HMAC) algorithms are supported. RSA and ECDSA algorithms are not accepted.
• Use jwt_verify_hs256 to confirm the generated token validates correctly with the same secret.
• For stronger signatures use jwt_sign_hs384 or jwt_sign_hs512.