JSON Web Tokens

Authentication with vlayer services is handled via JSON Web Tokens (JWTs). Since JWTs are Base64-encoded by default, it can be difficult to visually inspect them when debugging failed authentication attempts.

For most use cases, generating a JWT through the dashboard is sufficient. However, for local development or debugging, the vlayer CLI includes a helpful utility for generating and verifying JWTs compatible with the vlayer network.

This utility is available under the vlayer jwt command.

Generating/encoding new JWTs

Generating new JWTs can be done using vlayer jwt encode command.

Typical usage when targeting vlayer devnet would look as follows:

$ vlayer jwt encode -p docker/fixtures/jwt-authority.key --subject deadbeef --host "api.x.com" --port 443
2025-03-28T06:47:46.993637Z  INFO vlayer::commands::jwt: Claims {
    host: "api.x.com",
    port: 443,
    exp: 18446744073709551615,
    sub: "deadbeef",
}
2025-03-28T06:47:47.002804Z  INFO vlayer::commands::jwt: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJob3N0IjoiYXBpLnguY29tIiwicG9ydCI6NDQzLCJleHAiOjE4NDQ2NzQ0MDczNzA5NTUxNjE1LCJzdWIiOiJkZWFkYmVlZiJ9.EPvz_8kHV1FW3SObjzmyN_WOCbmQvBNHHDsjMYd0M__lbfpeDUJinM8vLJ4KLYpo_nqEBipq4rl656pImXPNHKpmyrjWaEueG5bNY67Vyxa7A8B7jHkqnVpFe7L5kX-5M-kC-8JLxmlsNAMhm40vrmiC3uqFqnFAiXxefV-usnlGgnLMZSWfo5PwRFhayEsObHCJImsj5tKIUUS1d2dDzwRhBmrAIvOihbvAVnSQsrHTMxfs2-OsUQjRkDfEsBhz46Ei1fBRFoAj0-SQH04YBaWkQlNqStXOL2n_2eQyUnAJH_5sn7lSmXQLPhUlNHdh2Ly8DJ6qcZpGEoM1fKXL7nOIay5pEThGPqAZGiXL3yMt-E550EX_ccvTIYzSBqZ671Q4ziy1acNIWBsL5abm-Rui-crQHSXAH6q8ADQCEdMZT6jw6XeNxt-AQIh_GduVlIALoZBYrfsJi8MfcWsYwQ36TAzp67Wb7LmqXGWfVv0_XSNLjFMc-WGqTk195jfY-Sb8v11opF7BKEW1sH89ALCGX0dWMTablAzox8eKwawEZWmL0xEXQwqARqJD20EnWW6tZ3X8LV5JAVNhAfM6Yp9wJ_BWJmlN_5P7F6ODy_nTlr5tJ5yLpX2OLRQQrsIyRB-Y4VdH8K5riIIOPcjapXtIoqEaFNmkls5hX_3jzKk

Here we are generating a new JWT token with subject equal deadbeef and web-proof target host api.x.com:443.

We are also employing the default devnet private key to correctly sign the token stored at docker/fixtures/jwt-authority.key.

Validating/decoding JWTs

Validating JWTs can be done using vlayer jwt decode command.

Decoding tokens that were signed using vlayer devnet's default private key would look as follows:

$ vlayer jwt decode -p docker/fixtures/jwt-authority.key.pub eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJob3N0IjoiYXBpLnguY29tIiwicG9ydCI6NDQzLCJleHAiOjE4NDQ2NzQ0MDczNzA5NTUxNjE1LCJzdWIiOiJkZWFkYmVlZiJ9.EPvz_8kHV1FW3SObjzmyN_WOCbmQvBNHHDsjMYd0M__lbfpeDUJinM8vLJ4KLYpo_nqEBipq4rl656pImXPNHKpmyrjWaEueG5bNY67Vyxa7A8B7jHkqnVpFe7L5kX-5M-kC-8JLxmlsNAMhm40vrmiC3uqFqnFAiXxefV-usnlGgnLMZSWfo5PwRFhayEsObHCJImsj5tKIUUS1d2dDzwRhBmrAIvOihbvAVnSQsrHTMxfs2-OsUQjRkDfEsBhz46Ei1fBRFoAj0-SQH04YBaWkQlNqStXOL2n_2eQyUnAJH_5sn7lSmXQLPhUlNHdh2Ly8DJ6qcZpGEoM1fKXL7nOIay5pEThGPqAZGiXL3yMt-E550EX_ccvTIYzSBqZ671Q4ziy1acNIWBsL5abm-Rui-crQHSXAH6q8ADQCEdMZT6jw6XeNxt-AQIh_GduVlIALoZBYrfsJi8MfcWsYwQ36TAzp67Wb7LmqXGWfVv0_XSNLjFMc-WGqTk195jfY-Sb8v11opF7BKEW1sH89ALCGX0dWMTablAzox8eKwawEZWmL0xEXQwqARqJD20EnWW6tZ3X8LV5JAVNhAfM6Yp9wJ_BWJmlN_5P7F6ODy_nTlr5tJ5yLpX2OLRQQrsIyRB-Y4VdH8K5riIIOPcjapXtIoqEaFNmkls5hX_3jzKk
2025-03-28T06:48:59.290970Z  INFO vlayer::commands::jwt: Header {
    typ: Some(
        "JWT",
    ),
    alg: RS256,
    cty: None,
    jku: None,
    jwk: None,
    kid: None,
    x5u: None,
    x5c: None,
    x5t: None,
    x5t_s256: None,
}
2025-03-28T06:48:59.292317Z  INFO vlayer::commands::jwt: Claims {
    host: "api.x.com",
    port: 443,
    exp: 18446744073709551615,
    sub: "deadbeef",
}