Skip to main content
When building applications with Dfns, you’ll typically want separate environments for development, staging, and production. This guide covers best practices for setting up and managing multiple Dfns organizations for environment separation.

​
When to use multiple organizations

Use separate organizations for each environment when:
  • You need isolated wallets, users, and policies per environment
  • You want to test policy changes without affecting production
  • Different team members should have access to different environments
  • You need to prevent accidental production operations during development
Each Dfns organization is fully isolated. Wallets, users, policies, and configurations in one organization cannot access or affect another organization.

​
Setting up your organizations

Contact Dfns support to create organizations for each environment. We recommend a naming convention that clearly identifies each environment:
EnvironmentOrganization namePurpose
DevelopmentAcme Corp - DevLocal development and testing
StagingAcme Corp - StagingPre-production testing, QA
ProductionAcme Corp - ProductionLive application
The same email address can be used to create separate user accounts in different organizations. This allows your team members to access all environments with familiar credentials.

​
Service accounts per environment

As for the rest of the configuration, you will need to create separate service accounts for each environment. We recommend to use separate keys for each one of them. This provides:
  • Isolation: Compromised development credentials can’t affect production
  • Audit trails: Clear attribution of which environment performed actions
  • Different permissions: Broader permissions in dev, restricted in production
1

Generate unique keypairs per environment

Create separate keypairs for each environment:
# Development
openssl genrsa -out service-account-dev.pem 2048
openssl pkey -in service-account-dev.pem -pubout -out service-account-dev.public.pem

# Staging
openssl genrsa -out service-account-staging.pem 2048
openssl pkey -in service-account-staging.pem -pubout -out service-account-staging.public.pem

# Production
openssl genrsa -out service-account-prod.pem 2048
openssl pkey -in service-account-prod.pem -pubout -out service-account-prod.public.pem
2

Create service accounts in each organization

In each organization’s dashboard:
  1. Navigate to Settings > Developers > Service Accounts
  2. Create a service account with the corresponding public key
  3. Save the authentication token securely
3

Assign appropriate permissions

Consider granting broader permissions in development for easier testing, while restricting production to the minimum required:
EnvironmentRecommended approach
DevelopmentBroader permissions for rapid iteration
StagingMatch production permissions to catch issues
ProductionMinimum required permissions only

​
Configuration management

​
Environment variables

Structure your configuration to switch between environments:
config.ts
interface DfnsConfig {
  baseUrl: string
  orgId: string
  serviceAccountToken: string
  serviceAccountPrivateKey: string
}

const configs: Record<string, DfnsConfig> = {
  development: {
    baseUrl: 'https://api.dfns.io',
    orgId: process.env.DFNS_ORG_ID_DEV!,
    serviceAccountToken: process.env.DFNS_TOKEN_DEV!,
    serviceAccountPrivateKey: process.env.DFNS_PRIVATE_KEY_DEV!,
  },
  staging: {
    baseUrl: 'https://api.dfns.io',
    orgId: process.env.DFNS_ORG_ID_STAGING!,
    serviceAccountToken: process.env.DFNS_TOKEN_STAGING!,
    serviceAccountPrivateKey: process.env.DFNS_PRIVATE_KEY_STAGING!,
  },
  production: {
    baseUrl: 'https://api.dfns.io',
    orgId: process.env.DFNS_ORG_ID_PROD!,
    serviceAccountToken: process.env.DFNS_TOKEN_PROD!,
    serviceAccountPrivateKey: process.env.DFNS_PRIVATE_KEY_PROD!,
  },
}

export const dfnsConfig = configs[process.env.NODE_ENV || 'development']

​
Secrets management

Store credentials securely using a secrets manager:
EnvironmentRecommended storage
DevelopmentLocal .env file (gitignored)
Staging/ProductionAWS Secrets Manager, HashiCorp Vault, or similar
Never commit service account tokens or private keys to version control.
Example .env structure:
.env.development
DFNS_ORG_ID_DEV=or-xxxxx-xxxxx-xxxxxxxxx
DFNS_TOKEN_DEV=eyJhbGciOiJS...
DFNS_PRIVATE_KEY_DEV="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"

​
Policies and permissions

Policies and permissions must be configured separately in each organization. Consider:

​
Development environment

  • Simpler policies or no policies for rapid iteration
  • Broader permissions for all developers
  • Use testnet chains only

​
Staging environment

  • Mirror production policies to catch issues before release
  • Test policy changes here before applying to production
  • Use testnet chains for most testing

​
Production environment

  • Strict policies with appropriate approval requirements
  • Minimum necessary permissions
  • Mainnet chains for real transactions
Document your production policies and permissions so you can replicate them in staging for accurate testing.

​
Webhooks

Configure webhooks separately for each environment to send events to the appropriate endpoints:
EnvironmentWebhook URL
Developmenthttps://dev.example.com/webhooks/dfns or local tunnel
Staginghttps://staging.example.com/webhooks/dfns
Productionhttps://api.example.com/webhooks/dfns
For local development, use a tunneling service to receive webhooks on your local machine.

Creating a service account

Step-by-step service account setup

WebAuthn configuration

Configure passkeys for multiple domains

Managing policies

Set up transaction policies

Webhooks

Configure event notifications