Certificate-Based Authentication

Use certificate-based authentication to encrypt your login payload, request a bearer token securely, and implement the recommended authentication method for new Verto integrations.

✅
The Gold Standard
This is the only supported method for new integrations. It utilizes an RSA-encrypted challenge-response mechanism that expires every 30 seconds.

✅ Before you start

Complete these setup steps before you build your auth module:

Create or access your sandbox environment through Quickstart.
Generate your Client ID, API Key, and certificate material in Access Your Credentials.
Install an RSA-compatible crypto library in your backend environment.
Make sure your backend can generate a current UNIX timestamp and base64-encode the encrypted payload.

1️⃣ Step 1 - Obtain Credentials

You require your Client ID and API Key from the portal to begin.

🔗
Resource: Access Your Credentials →

2️⃣ Step 2 - Generate Public Key

Log in to your Sandbox Dashboard.
Navigate to Verto API -> Certificates.
Select Generate Public Key.
Verify your identity via OTP.
Copy the RSA Public Key and store it as a .pem file or environment string.

Store the certificate material securely because your backend will need it every time it generates an encrypted login payload.

3️⃣ Step 3 - Encrypt the Payload

You must encrypt a concatenated string of your API_KEY and a TIMESTAMP.

Component	Format
Payload	`YOUR_API_KEY:UNIX_TIMESTAMP_MS`
Algorithm	`RSA-OAEP` with `SHA-512`

Generate the payload immediately before login so the timestamp stays within the accepted validity window.

💻 Code Implementation

import time
import base64
from cryptography.hazmat.primitives import serialization,hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend

api_key = '<API_KEY>' # api key

timestamp = int(time.time() * 1000) # timestamp is the current time in milliseconds since Unix epoch

path_to_certificate = 'path_to_certificate/certificate_key_file.pem'

with open(path_to_certificate, 'rb') as key_file:
    public_key = serialization.load_pem_public_key(
        key_file.read(),
        backend=default_backend()
    )

payload = f"{api_key}:{timestamp}" # payload is the api key and the timestamp

encrypted = public_key.encrypt(
    payload.encode(),
    padding.OAEP(
        mgf=padding.MGF1(algorithm=hashes.SHA512()),
        algorithm=hashes.SHA512(),
        label=None
    )
)
print(base64.b64encode(encrypted).decode('utf-8'))

const crypto = require('crypto');
const fs = require('fs');
const path = require('path');

// 1. Define your credentials
const apiKey = 'YOUR_ACTUAL_VERTO_API_KEY'; 

// 2. Load your public key file (.pem)
// Change 'public_key.pem' to the actual path of your downloaded file
const publicKeyPath = path.join(__dirname, 'public_key.pem'); 
const publicKey = fs.readFileSync(publicKeyPath, 'utf8');

// 3. Generate the 13-digit UNIX timestamp in milliseconds
const timestamp = Date.now();

// 4. Create the payload string
const payload = `${apiKey}:${timestamp}`;

// 5. Encrypt using RSA-OAEP with SHA-512
const encrypted = crypto.publicEncrypt({
    key: publicKey,
    oaepHash: 'sha512' // Node automatically sets MGF1 to SHA-512 when this is set
}, Buffer.from(payload));

// 6. Convert to Base64
const base64Payload = encrypted.toString('base64');

console.log("--- COPY THIS FOR STEP 4 ---");
console.log(base64Payload);

4️⃣ Step 4 - Execute Authenticated Login

Send the base64-encoded apiKey payload to the migrated company login endpoint.

curl --request POST \
  --url https://api-company-sandbox.vertofx.com/users/login \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "YOUR_CLIENT_ID",
  "apiKey": "BASE64_ENCRYPTED_PAYLOAD",
  "mode": "apiKey"
}'

Store the returned bearer token securely and send it in the Authorization: Bearer <token> header for subsequent protected API requests.

Use the migrated company login route above for new sandbox integrations instead of legacy api-v3-sandbox.vertofx.com/users/login or older unified auth paths.

🎯 Next Steps


Environments → Map your sandbox and production URLs correctly.	Authentication → Return to the main auth guide and compare available methods.

comments

Talk to Verto

Get help with authentication, receive flows, wallets, FX conversion, payouts, or Atlas platform setup.

rocket

Plan your go-live

Review the requirements you need before moving your integration into production.

Certificate-Based Authentication

The Gold Standard

✅ Before you start

1️⃣ Step 1 - Obtain Credentials

Resource: Access Your Credentials →

2️⃣ Step 2 - Generate Public Key

3️⃣ Step 3 - Encrypt the Payload

💻 Code Implementation

4️⃣ Step 4 - Execute Authenticated Login

🎯 Next Steps