​
Overview

OpenFX uses Ed25519 asymmetric key pairs for request signing. You generate a key pair locally, register the public key with OpenFX, and keep the private key securely in your infrastructure. The server never sees your private key. This guide covers the full lifecycle of your signing keys: generation, registration, secure storage, rotation, and revocation.

​
Generating Ed25519 Key Pairs

Ed25519 is a modern elliptic-curve signature scheme that produces compact 64-byte signatures with excellent performance. Key pairs consist of:
  • Private key (32-byte seed) — kept secret in your infrastructure
  • Public key (32 bytes) — registered with OpenFX
# Generate a new Ed25519 private key in PEM format
openssl genpkey -algorithm Ed25519 -out openfx_ed25519.pem

# Extract the public key in PEM format (for registration with OpenFX)
openssl pkey -in openfx_ed25519.pem -pubout -out openfx_ed25519_pub.pem

# View the public key (Base64-encoded)
cat openfx_ed25519_pub.pem
The generated PEM files will look like this:
openfx_ed25519.pem (PRIVATE -- never share)
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIGh...
-----END PRIVATE KEY-----
openfx_ed25519_pub.pem (register with OpenFX)
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAb7K3p...
-----END PUBLIC KEY-----
The private key file grants full signing authority for your OpenFX integration. Treat it with the same care as a database root password or a TLS private key. Never commit it to version control, paste it in chat, or store it in plaintext on disk outside of a secrets manager.

​
Registering Your Public Key

After generating your key pair, register the public key with OpenFX so the server can verify your request signatures.

​
Via the Dashboard

  1. Log in to the OpenFX Dashboard.
  2. Navigate to Settings > API Keys.
  3. Click Create API Key.
  4. Enter a descriptive label (e.g., production-payments-service).
  5. Select the role: read or write.
  6. Paste your public key PEM content into the Public Key field.
  7. Click Create.
  8. Copy the generated API key (prefixed ofx_sk_sandbox_ or ofx_sk_live_). This is shown only once.

​
Via Onboarding

If your OpenFX account is provisioned through a partner program, your account manager will provide instructions for submitting your public key during the onboarding process.
Each API key is bound to exactly one public key. To use a different key pair, create a new API key with the new public key and revoke the old one.

​
Storing Private Keys Securely

Your Ed25519 private key is the most sensitive credential in your OpenFX integration. Choose a storage solution appropriate for your security requirements. For production workloads handling significant payment volumes, store your private key in a hardware-backed key store:
ProviderServiceEd25519 Support
AWSCloudHSM or KMSEd25519 supported via CloudHSM; KMS supports Ed25519 signing keys
Google CloudCloud KMSEd25519 supported for asymmetric signing
AzureKey Vault (Managed HSM)Ed25519 supported in Premium/Managed HSM tiers
HashiCorpVault Transit Secrets EngineEd25519 supported natively
With HSM/KMS, the private key never leaves the secure hardware. Your application sends the signing payload to the KMS API, which returns the signature. 
# Example: Signing with AWS KMS (pseudocode)
import boto3
import base64

kms_client = boto3.client("kms")

response = kms_client.sign(
    KeyId="arn:aws:kms:us-east-1:123456789:key/your-key-id",
    Message=signing_payload.encode("utf-8"),
    MessageType="RAW",
    SigningAlgorithm="ECDSA_SHA_256",  # Use your KMS key's algorithm
)

signature_b64 = base64.b64encode(response["Signature"]).decode("utf-8")

​
Acceptable: Environment Variables or Secrets Manager

For smaller deployments, inject the private key via environment variables or a secrets manager at runtime: 
# Set as environment variable (base64-encoded PEM)
export OPENFX_PRIVATE_KEY=$(base64 < openfx_ed25519.pem)

import os
import base64
from cryptography.hazmat.primitives import serialization

# Load from environment variable at startup
private_key_pem = base64.b64decode(os.environ["OPENFX_PRIVATE_KEY"])
private_key = serialization.load_pem_private_key(private_key_pem, password=None)
If using environment variables, prefer a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault) that injects values at container startup rather than baking them into deployment manifests or CI/CD configuration files.

​
Never Do This

These practices are never acceptable for private key storage:
  • Committing the key to a Git repository (even a private one)
  • Hardcoding the key in application source code
  • Storing the key in a configuration file on a shared filesystem
  • Sending the key via email, Slack, or any messaging platform
  • Storing the key in a browser-accessible location
  • Logging the key in application logs or error tracking services

​
Key Rotation

Rotating your signing key pair regularly is a security best practice. OpenFX supports seamless key rotation with zero-downtime transition.

​
Rotation Process

1. Generate new key pair        (your infrastructure)
         |
2. Register new public key      (OpenFX Dashboard -- creates a new API key)
         |
3. Deploy new credentials       (update your services to use the new key pair)
         |
4. Verify new key works         (confirm successful requests with new credentials)
         |
5. Revoke old API key           (OpenFX Dashboard -- disables the old key)
         |
6. Remove old private key       (delete from your secrets store)

​
Step-by-Step

1. Generate a new key pair. Follow the generation instructions above to create a fresh Ed25519 key pair. 2. Register the new public key. Create a new API key in the OpenFX Dashboard with the new public key. You will now have two active API keys temporarily. 3. Update your services. Deploy your application with the new API key and private key. If you have multiple services, roll out the update progressively. 4. Verify in production. Confirm that requests signed with the new key pair succeed. Monitor for authentication_error responses during the transition. 5. Revoke the old API key. Once all traffic is using the new credentials, revoke the old API key in the Dashboard. Requests signed with the old key will immediately start returning 401. 6. Delete the old private key. Remove the old private key from all secrets stores, environment variables, and backups.
During the transition window (steps 2-5), both key pairs are valid simultaneously. This allows rolling deployments without authentication failures. Keep this window as short as operationally practical.

​
Rotation Frequency

Risk LevelRecommended Frequency
StandardEvery 90 days
High-value (> $1M daily volume)Every 30 days
After personnel changeImmediately
After suspected compromiseImmediately

​
Multiple API Keys for Different Environments

Maintain separate credentials for each environment and each service that connects to the OpenFX API.
EnvironmentKey PrefixUse
Sandboxofx_sk_sandbox_Development, testing, CI/CD
Productionofx_sk_live_Live payment operations
Sandbox and production are fully isolated. A sandbox API key will not authenticate against the production environment, and vice versa. Each environment requires its own Ed25519 key pair.

​
Per-Service Key Separation

If your architecture has multiple services that call the OpenFX API, issue each service its own API key and key pair: 
payments-service       --> ofx_sk_live_payments_xxx   (write role)
reconciliation-worker  --> ofx_sk_live_recon_xxx      (read role)
dashboard-backend      --> ofx_sk_live_dashboard_xxx  (read role)
This provides:
  • Least privilege — each service has only the permissions it needs
  • Audit isolation — API activity is attributable to a specific service
  • Blast radius reduction — revoking one compromised key does not affect other services
  • Independent rotation — each service can rotate on its own schedule

​
Best Practices Summary

Follow these practices for production-grade key management:
  • Generate unique key pairs per environment. Never share keys between sandbox and production.
  • Use the minimum required role. Read-only services should use read-only keys.
  • Issue separate keys per service. Do not share a single API key across multiple applications.
  • Store private keys in HSM or KMS for production payment workloads.
  • Rotate keys on a regular schedule (at least every 90 days).
  • Revoke immediately when team members with key access depart or when compromise is suspected.
  • Monitor authentication failures. A spike in authentication_error responses may indicate misconfiguration or attempted abuse.
  • Keep an inventory. Maintain a record of which API keys are active, which services use them, and when they were last rotated.

​
Emergency Revocation

If you suspect a private key has been compromised, revoke the associated API key immediately.

​
Immediate Steps

  1. Revoke the API key in the OpenFX Dashboard under Settings > API Keys. Click the key and select Revoke. This takes effect instantly.
  2. Contact OpenFX support at api-support@openfx.com or call the emergency support line. Inform them of the suspected compromise so they can audit recent activity on your account.
  3. Generate a new key pair and register the new public key.
  4. Deploy the new credentials to your services.
  5. Review recent API activity in the Dashboard to identify any unauthorized requests made with the compromised key. Check for unexpected payments, counterparty creations, or webhook subscription changes.
Revoking an API key is irreversible and immediate. All in-flight requests using the revoked key will fail with 401. Make sure your new credentials are ready to deploy before revoking in a production environment, unless you suspect active exploitation — in that case, revoke first and deploy second.

​
What OpenFX Does During Compromise Response

When notified of a potential key compromise, the OpenFX security team will:
  • Audit all requests made with the affected API key in the past 30 days
  • Flag any suspicious payment or configuration changes for manual review
  • Place temporary holds on pending payments if instructed by you
  • Provide a detailed activity log for your incident response