Keypair Authentication

Engine supports keypair authentication allowing your app to generate short-lived access tokens.

• You don't want an access token to be reused for a long duration if shared or compromised.
• You want to restrict what each access token can do (e.g. specific calls).

Generate a cryptographic keypair in your terminal with openssl.

These commands generate a private and public key with the ES256 algorithm.

openssl ecparam -name prime256v1 -genkey -noout -out private.key

openssl ec -in private.key -pubout -out public.key

• Navigate to the Engine dashboard.
• Select Access Tokens.
• Select Keypair Authentication.
  • Note: If this option is unavailable, your Engine instance may not be configured to support keypairs.
• Select Add Public Key.
• Add your public key including the ----- boundary lines.

This step must be done for each request.

import jsonwebtoken from "jsonwebtoken";
 
const payload = {
  iss: publicKey,
};
const accessToken = jsonwebtoken.sign(payload, privateKey, {
  algorithm: "ES256", // The keypair algorithm
  expiresIn: "15s", // Invalidate after 15 seconds
});

Provide the access token in the Authorization header.

await fetch(`${engineBaseUrl}/backend-wallet/get-all`, {
  headers: {
    authorization: `Bearer ${accessToken}`,
  },
});

Set the environment variable ENABLE_KEYPAIR_AUTH="true" and restart your Engine.

The following algorithms can be used.

Refer to the OpenSSL documentation on generating keypairs for different algorithms.

Remember to change algorithm in the jsonwebtoken.sign() call on Step 3. Sign a JWT with your private key.