JSON Web Token (JWT)

What is JSON Web Token?

JSON Web Token (JWT) is an open, industry standard RFC 7519 method for representing claims securely between two parties. You can enable JWT in your API Key and send requests with JWT to ensure only authorized requests are available.

How to use it?

It's easy to enable JWT and send requests with JWT. You just need to follow the below instructions:

Generate RSA-256 keys

Generate your own RSA-256 public and private key with 2048 length. Below is the example using OpenSSL.

# generate rsa key
openssl genrsa -out jwtRSA256-private.pem 2048
openssl rsa -in jwtRSA256-private.pem -pubout -outform PEM -out jwtRSA256-public.pem

Enable JWT in 4EVERLAND RPC

• Login > Dashboard > RPC > API Key > Setting

• Enable the JTW and input the public key generated in previous step.

• You will get the public key ID （uuid) after clicking "Add"

Copy ID (uuid) for JWT generation

Generate the JWT

Once you've enabled the JWT, it's required to add the JWT in all the requests header. Below is the example of generating JWT using https://jwt.io/You need HEADER, PAYLOAD, & SIGNATURE to generate a JWT.

Header

Field	Description	Example
alg	The signing algorithm being used	RS256
typ	The type of the token	JWT

You can use your terminal to encode the header.

# To encode a header
header=`echo -n '{"alg": "RS256","typ": "JWT","kid": "c6a5278e-ce1d-4f54-b7fa-f8d90f8b5756"}' | base64 | sed s/\+/-/ | sed -E s/=+$//`

Payload

Field	Required	Description	Example
uuid	TRUE	The ID generated in the previous step in the dashboard.	00000000-0000-0000-0000-000000000000
exp	FALSE	The expiry time. It should be no later than current time + 24 hours. Unix timestamp format.	1656907527

You can convert a human-readable timestamp to epoch by command below.

date -j -f "%Y-%m-%d %H:%M:%S" "2022-07-10 15:58:50" "+%s"

Make sure your expiration time is no longer than current time + 24 hours.You can encode your payload by command below.

#To encode a payload
payload=`echo -n '{"uuid": "00000000-0000-0000-0000-000000000000","exp": "1656907527"}' | base64 | sed s/\+/-/ | sed -E s/=+$//`

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

# To encode a signature
sig=`echo -n "$header.$payload" | openssl dgst -sha256 -binary -sign jwtRSA256-private.pem  | openssl enc -base64 | tr -d '\n=' | tr -- '+/' '-_'`

JWT

Your JWT is the combination of your encoded header.payload.signature.

# JWT = header.payload.signature
jwt=`echo $header.$payload.$sig`
echo $jwt

Verify your jwt by the debugger.

Send request with JWT

After generating the JWT, you would need to add the JWT as a part of your request header -H "Authorization: Bearer entry.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $jwt" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}' \
"https://bsc-mainnet.4everland.org/v1/<YOUR-API-KEY>"

What if the JWT is incorrect ?

If you have enabled the JWT but sending requests without JWT or with incorrect JWT, you will receive a http 401 error status code and also the response below.

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -40302,
        "message": "Json Web Token parsing failed."
    }
}

You should either disable the JWT setting or send requests with correct JWT.