> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate JWS keys

> Generate a public-private key pair, register the public key, and sign Business Accounts API requests that move money with a JSON Web Signature (JWS).

Set up a public-private key pair to sign protected Business Accounts API requests. Business Accounts API requests that move money must include a JSON Web Signature (JWS). A JWS digitally signs data to ensure its integrity and authenticity. Protected actions include [creating outbound transfers](https://docs.fintoc.com/api/business-accounts-api/transfers/transfers-create.md) and returning inbound transfers.

## Generate a public and private JWS key pair

Run these commands in your terminal:

```bash theme={null}
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -outform PEM -pubout -out public_key.pem
```

These commands generate two files:

* `private_key.pem`, containing your private key.
* `public_key.pem`, containing your public key.

The files use the following formats:

```text public_key.pem theme={null}
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPPSwkMAHrLy6ZY+cOIP
jl6PxkrKJBicwMBMgFPf0Vtqe6QWepeOWXQuLgW+cSDI0KBjk8eZQEVB7GY3OwOl
DcknxUkaVueEvsDiY74xeC1iN2Gfb6HXd2JqgDWdWy/HNv2eUe9kmsSPSSgruA8Y
DvR6lpjPvAEJHP4Sg/B+9c0gBTDmqadL8UD291D7JbHmG4lIBT5NbhpOVnSBN0aC
R6ioxWz+VJoz68qsxHQ69TYhl8/jG79ocvZsZEWCWc/Kv7SP6/cPJHu0oGWVZwa4
5BtPLeMQ9ZleHdV6RCUbxFXKzbZF5fKQ+z5NWk+hMz5TCs4jwmg1nodWyW+bL7K9
YQIDAQAB
-----END PUBLIC KEY-----
```

```text private_key.pem theme={null}
-----BEGIN PRIVATE KEY-----
<redacted example private key content>
-----END PRIVATE KEY-----
```

> [!WARNING]
>
> **Never share your JWS private key**
>
> Your JWS private key is sensitive and must remain confidential. Fintoc never asks for this key. Anyone with your private key can sign malicious transfer requests on your behalf.

## Upload your public key to the dashboard

1. Go to [dashboard.fintoc.com](https://dashboard.fintoc.com).
2. Open **API Keys** in the sidebar.
3. If your organization has products that require JWS, open **JWS Public Keys**, select **Add JWS Key**, and upload your JWS public key.

## Generate a signature

After you upload your public key to the Fintoc dashboard, generate signatures with your private key. Each signature protects the integrity and authenticity of a Business Accounts API call that moves money.

## Generate signatures with an SDK

The [Node SDK](https://github.com/fintoc-com/fintoc-node) and [Python SDK](https://github.com/fintoc-com/fintoc-python) generate signatures for you. Pass the private key when you initialize the Fintoc client. The SDK then signs each protected request:

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

// Provide a path to your PEM file
const fintoc = new Fintoc('YOUR_API_KEY', 'private_key.pem');

// Or pass the PEM key directly as a string
// const fintoc = new Fintoc('YOUR_API_KEY', process.env.JWS_PRIVATE_KEY);

// The client now signs protected transfer requests
```

```python Python theme={null}
import os

from fintoc import Fintoc

# Provide a path to your PEM file
client = Fintoc("YOUR_API_KEY", jws_private_key="private_key.pem")

# Or pass the PEM key directly as a string
# client = Fintoc("YOUR_API_KEY", jws_private_key=os.environ.get('JWS_PRIVATE_KEY'))

# The client now signs protected transfer requests
```

## Generate a signature manually

If you want to write your own implementation or use a different programming language, follow these steps:

### Prepare the payload

JWS signature generation operates on the exact JSON string sent in the HTTP request. Create that string by serializing your outbound transfer request body with your language's JSON serializer.

```javascript Node theme={null}
const body = {
  amount: 100000,
  currency: 'MXN',
  account_id: 'YOUR_ACCOUNT_ID',
  counterparty: {
    account_number: '000000000000000000'
  }
};

const rawBody = JSON.stringify(body);
```

```python Python theme={null}
import json

body = {
    "amount": 100000,
    "currency": "MXN",
    "account_id": "YOUR_ACCOUNT_ID",
    "counterparty": {
        "account_number": "000000000000000000"
    }
}

raw_body = json.dumps(body)
```

> [!NOTE]
>
> **JSON string must be consistent**
>
> When serializing your request body to JSON, you must use the exact same string for two purposes:
>
> 1. Creating the JWS signature
> 2. Sending as the payload in your HTTP request
>
> Any difference between the JSON used to create the JWS signature and the HTTP request payload may invalidate the signature.

### Load the private key and configure headers

Load your private key from the PEM file and configure the protected JWS header. The header includes the `RS256` signing algorithm, a unique `nonce`, and the current Unix timestamp in `ts`. The `crit` field identifies `ts` and `nonce` as critical fields.

```javascript Node theme={null}
// Load the private key
const privateKey = readFileSync('./private_key.pem', 'utf8');

// Define the JWS headers
const headers = {
  alg: 'RS256',                                  // Signing algorithm. Must be "RS256"
  nonce: crypto.randomBytes(16).toString('hex'), // Unique string for each request
  ts: Math.floor(Date.now() / 1000),             // Unix timestamp in seconds
  crit: ['ts', 'nonce']                          // Critical headers
};
```

```python Python theme={null}
# Load the private key
with open('./private_key.pem', 'rb') as f:
    private_key = serialization.load_pem_private_key(
        f.read(),
        password=None
    )

# Define the JWS headers
headers = {
    "alg": "RS256",                  # Signing algorithm. Must be "RS256"
    "nonce": secrets.token_hex(16),  # Unique string for each request
    "ts": int(time.time()),          # Unix timestamp in seconds
    "crit": ["ts", "nonce"]          # Critical headers
}
```

#### Prevent replay attacks

Fintoc uses the `nonce` and `ts` headers during JWS authentication to protect against [replay attacks](https://en.wikipedia.org/wiki/Replay_attack) and ensure request integrity.

Include a unique, random `nonce` in every request. The `nonce` makes each signature distinct, even when you send the same data multiple times. Fintoc accepts each `nonce` only once and rejects requests that reuse a `nonce`.

The Unix timestamp in `ts` records when you created the request. Fintoc validates that the timestamp falls within a 2-minute window and rejects outdated requests.

Together, `nonce` and `ts` prevent replays: Fintoc rejects any intercepted request that reuses a `nonce` or falls outside the timestamp window.

### Generate the signing input

Create the JWS signing input by joining the base64url-encoded `headers` and `raw_body` with a period (`.`). Encode both values without padding:

```javascript Node theme={null}
// Base64url-encode the protected JWS header without padding
const protectedBase64 = Buffer.from(JSON.stringify(headers))
  .toString('base64url');

// Base64url-encode rawBody without padding
const payloadBase64 = Buffer.from(rawBody)
  .toString('base64url');

// Join the encoded protected header and payload
const signingInput = `${protectedBase64}.${payloadBase64}`;
```

```python Python theme={null}
# Base64url-encode the protected JWS header without padding
protected_base64 = base64.urlsafe_b64encode(
    json.dumps(headers).encode()
).rstrip(b'=').decode()

# Base64url-encode raw_body without padding
payload_base64 = base64.urlsafe_b64encode(
    raw_body.encode()
).rstrip(b'=').decode()

# Join the encoded protected header and payload
signing_input = f"{protected_base64}.{payload_base64}"
```

### Generate the JWS token signature

Create the cryptographic signature from the signing input and your private key:

1. Sign the signing input with your private key using RSA and PKCS #1 v1.5 padding.
2. Base64url-encode the resulting signature without padding.

```javascript Node theme={null}
// Sign the signing input
const signatureRaw = crypto.createSign('sha256')
  .update(signingInput)
  .sign({
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_PADDING
  });

// Base64url-encode the raw signature without padding
const signatureBase64 = Buffer.from(signatureRaw)
  .toString('base64url');
```

```python Python theme={null}
# Sign the signing input
signature_raw = private_key.sign(
    signing_input.encode(),
    padding.PKCS1v15(),
    hashes.SHA256()
)

# Base64url-encode the raw signature without padding
signature_base64 = base64.urlsafe_b64encode(signature_raw).rstrip(b'=').decode()
```

### Verify the JWS token (optional)

Some libraries re-encode JSON payloads with different spacing, key ordering, or character encoding. To debug a signature, decode the payload locally and confirm that it matches the `raw_body` sent in the HTTP request. Do not share a token that contains sensitive transfer data.

```javascript Node theme={null}
const token = `${protectedBase64}.${payloadBase64}.${signatureBase64}`;
console.log(token);

const payload = Buffer.from(payloadBase64, 'base64url').toString();
console.log(payload); // Should equal rawBody sent in the HTTP request
```

```python Python theme={null}
token = f"{protected_base64}.{payload_base64}.{signature_base64}"
print(token)

payload = base64.urlsafe_b64decode(
    payload_base64 + '=' * (-len(payload_base64) % 4)
)
print(payload.decode())  # Should equal raw_body sent in the HTTP request
```

### Construct the `Fintoc-JWS-Signature` header

Construct the `Fintoc-JWS-Signature` header by concatenating the protected header and signature:

```javascript Node theme={null}
const jwsSignatureHeader = `${protectedBase64}.${signatureBase64}`;
```

```python Python theme={null}
jws_signature_header = f"{protected_base64}.{signature_base64}"
```

## Use the complete example

The following functions combine the manual signature steps. Install the Python `cryptography` package before running the Python example.

```javascript Node theme={null}
const crypto = require('crypto');
const { readFileSync } = require('fs');

function generateJwsSignatureHeader(rawBody) {
  // Read private key
  const privateKey = readFileSync('./private_key.pem', 'utf8');

  const headers = {
    alg: 'RS256',
    nonce: crypto.randomBytes(16).toString('hex'),
    ts: Math.floor(Date.now() / 1000),
    crit: ['ts', 'nonce']
  };

  const protectedBase64 = Buffer.from(JSON.stringify(headers))
    .toString('base64url');

  const payloadBase64 = Buffer.from(rawBody)
    .toString('base64url');

  const signingInput = `${protectedBase64}.${payloadBase64}`;
  const signatureRaw = crypto.createSign('sha256')
    .update(signingInput)
    .sign({
      key: privateKey,
      padding: crypto.constants.RSA_PKCS1_PADDING
    });

  const signatureBase64 = Buffer.from(signatureRaw)
    .toString('base64url');

  return `${protectedBase64}.${signatureBase64}`;
}

const payload = {
  amount: 100000,
  currency: 'MXN',
  account_id: 'YOUR_ACCOUNT_ID',
  counterparty: {
    account_number: '000000000000000000'
  }
};
const rawBody = JSON.stringify(payload); // Exact payload to send in the HTTP request

// Signature to include in the 'Fintoc-JWS-Signature' request header
const jwsSignatureHeader = generateJwsSignatureHeader(rawBody);
```

```python Python theme={null}
import base64
import json
import secrets
import time

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization


def generate_jws_signature_header(raw_body):
    # Read private key
    with open('./private_key.pem', 'rb') as f:
        private_key = serialization.load_pem_private_key(
            f.read(),
            password=None
        )

    # Create headers
    headers = {
        'alg': 'RS256',
        'nonce': secrets.token_hex(16),
        'ts': int(time.time()),
        'crit': ['ts', 'nonce']
    }

    # Base64url-encode without padding
    protected_base64 = base64.urlsafe_b64encode(
        json.dumps(headers).encode()
    ).rstrip(b'=').decode()

    payload_base64 = base64.urlsafe_b64encode(
        raw_body.encode()
    ).rstrip(b'=').decode()
    signing_input = f"{protected_base64}.{payload_base64}"

    # Sign the signing input
    signature_raw = private_key.sign(
        signing_input.encode(),
        padding.PKCS1v15(),
        hashes.SHA256()
    )

    signature_base64 = base64.urlsafe_b64encode(signature_raw).rstrip(b'=').decode()

    return f"{protected_base64}.{signature_base64}"


body = {
    "amount": 100000,
    "currency": "MXN",
    "account_id": "YOUR_ACCOUNT_ID",
    "counterparty": {
        "account_number": "000000000000000000"
    }
}
raw_body = json.dumps(body)  # Exact payload to send in the HTTP request

# Signature to include in the 'Fintoc-JWS-Signature' request header
jws_signature_header = generate_jws_signature_header(raw_body)
```

## Test the integration

Confirm your signature works before you go live. Using a `test` mode API key, sign a [create outbound transfer](https://docs.fintoc.com/api/business-accounts-api/transfers/transfers-create.md) request and send the signature in the `Fintoc-JWS-Signature` header.

1. Build the request body and serialize it with your JSON serializer.
2. Generate the signature from the serialized body with the function above.
3. Send the request with the `Fintoc-JWS-Signature` header set to the generated signature.

Fintoc returns `201 Created` and the created transfer when the signature is valid. A signature error or `401 Unauthorized` response can indicate a mismatched request body, a reused `nonce`, or a `ts` value outside the 2-minute window.
