tools/jwt-generate.1

.\" Automatically generated by Pandoc 3.7.0.2
.\"
.TH "JWT\-GENERATE" "1" "" "jwt\-generate User Manual" "LibJWT C Library"
.SH NAME
\f[B]jwt\-generate\f[R] \- Generate a JSON Web Token
.SH SYNOPSIS
.PP
\f[B]jwt\-generate\f[R] \f[B][options]\f[R]
.SH DESCRIPTION
\f[B]jwt\-generate\f[R] Generates and (optionally) signs a JSON Web
Token.
.PP
By default this will simply encode a JWT.
If you want a signature, then you must give a JWK key with the
\f[B]\-k\f[R] option.
Generating a signature requires specifying the algorithm, so it must
either be in the key file (as the \f[B]alg\f[R] attribute), or passed on
the command line with the \f[B]\-a\f[R] argument.
.PP
If \f[B]\-a\f[R] is specified and the key has an \f[B]alg\f[R]
attribute, they must match.
.PP
One token will be generated for each call.
You can specify claims using the \f[B]\-c\f[R] option.
By default, \f[B]jwt\-generate\f[R] will add the \f[B]iat\f[R] claim,
which is \f[B]Issued At\f[R] and is the time in seconds since the
\f[I]Unix Epcoch\f[R].
.PP
When using the \f[B]\-\-verbose\f[R] option, \f[B]jwt\-generate\f[R]
will print the JSON \f[I]HEADER\f[R] and \f[I]PAYLOAD\f[R] to
\f[B]stdout\f[R].
.PP
If used in conjunction with \f[B]\-\-print\f[R], the JSON will be piped
to the command\(cqs \f[B]stdin\f[R].
It will be called twice: once for \f[I]HEAD\f[R] and once for
\f[I]PAYLOAD\f[R].
.PP
One use is to pass it through \f[B]jq \-C\f[R] for indenting and
colorization.
Another would be to use an external program to inspect the
\f[I]PAYLOAD\f[R] contents.
A non\-0 exit status from the program will cause generating the token to
fail.
.SS Options
.TP
\f[B]\-h\f[R], \f[B]\-\-help\f[R]
Show common options and quit.
.TP
\f[B]\-l\f[R], \f[B]\-\-list\f[R]
List all supported algorithms that can be passed to the \f[B]\-a\f[R]
option and quit.
.TP
\f[B]\-v\f[R], \f[B]\-\-verbose\f[R]
Show the contents of the \f[I]HEADER\f[R] and \f[I]PAYLOAD\f[R] of the
JWT in addition to generating the token.
\f[B]NOTE\f[R] the header will not show the \f[B]typ\f[R] or
\f[B]alg\f[R] attributes since they do not get added until the final
step.
.TP
\f[B]\-q\f[R], \f[B]\-\-quiet\f[R]
Do not output anything except for hard errors.
On success you will only see the token generared.
.TP
\f[B]\-n\f[R], \f[B]\-\-no\-iat\f[R]
Do not add the iat (Issued\-At) time to the token.
Useful for a slightly smaller token, and for reproducible output.
.TP
\f[B]\-a\f[R] \f[I]ALG\f[R], \f[B]\-\-algorithm\f[R]=\f[I]ALG\f[R]
Specify the algorithm to be used when signing the token.
.TP
\f[B]\-k\f[R] \f[I]FILE\f[R], \f[B]\-\-key\f[R]=\f[I]FILE\f[R]
Path to a file containing a key in JSON Web Key format.
If your keys are in PEM or DER (or some other common format that
\f[I]OpenSSL\f[R] understands), then you can convert it to a JWK with
the \f[B]key2jwk(1)\f[R] tool.
.TP
\f[B]\-c\f[R] \f[I]CLAIM\f[R], \f[B]\-\-claim\f[R]=\f[I]CLAIM\f[R]
Add a claim to the JWT.
The format of \f[I]CLAIM\f[R] is
\f[B]t\f[R]:\f[B]key\f[R]=\f[B]value\f[R] Where \f[B]t\f[R] is the type
and is one of \f[B]i\f[R] for integer, \f[B]s\f[R] for string, or
\f[B]b\f[R] for boolean.
The value for integer must be parseable by \f[B]strtol(3)\f[R].
For boolean, any value starting with \f[B]0\f[R], \f[B]f\f[R], or
\f[B]F\f[R] will be interpreted as \f[B]false\f[R].
Anything else will be considered \f[B]true\f[R].
They \f[B]key\f[R] is any \f[I]ASCII\f[R] string.
.TP
\f[B]\-j\f[R] \f[I]JSON\f[R], \f[B]\-\-json\f[R]=\f[I]JSON\f[R]
Use JSON string as the payload of the token.
This will not replace, but be added to the payload.
The string must be in valid JSON, meaning either a \f[B]{}\f[R] object
or a \f[B][]\f[R] array.
.SH BUGS
See GitHub Issues: \c
.UR https://github.com/benmcollins/libjwt/issues
.UE \c
.SH AUTHOR
\f[B]jwt\-generate\f[R] was originally written by Jeremy Thien.
Major rewriting and man page by Ben Collins \c
.MT bcollins@libjwt.io
.ME \c
\&.
.SH SEE ALSO
\f[B]jwt\-verify(1)\f[R], \f[B]key2jwk(1)\f[R], \f[B]jwk2key(1)\f[R]