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

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

• Navigate to the Engine dashboard and select your engine.
• 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}`,
  },
});

To ensure this access token can only execute a specific payload, provide a SHA256 hash of the payload body as the bodyHash argument of the signed object.

Example: This access token is restricted to transfer 0.1 MATIC on Polygon to 0xE68FFAE106cc68A0e36Ba9Fd86f27337E3a71da6.

import { createHash } from "crypto";
import jsonwebtoken from "jsonwebtoken";
 
// Prepare the request payload body.
const body = JSON.stringify({
  to: "0xE68FFAE106cc68A0e36Ba9Fd86f27337E3a71da6",
  currencyAddress: "0x0000000000000000000000000000000000000000",
  amount: "0.1",
});
 
// Add a hash of `body` to the signed payload.
const payload = {
  iss: publicKey,
  bodyHash: createHash("sha256").update(body).digest("hex"),
};
const accessToken = jsonwebtoken.sign(payload, privateKey, {
  algorithm: "ES256",
});
 
// Call Engine with `body`.
await fetch(`${engineBaseUrl}/backend-wallet/137/transfer`, {
  headers: {
    "Content-Type": "application/json",
    authorization: `Bearer ${accessToken}`,
    "x-backend-wallet-address": "<engine_backend_wallet_address>",
  },
  body,
});

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.