Set up environments

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 our to create organizations for each environment. We recommend a naming convention that clearly identifies each environment:

Environment	Organization name	Purpose
Development	`Acme Corp - Dev`	Local development and testing
Staging	`Acme Corp - Staging`	Pre-production testing, QA
Production	`Acme Corp - Production`	Live 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

Recommended setup

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

Create service accounts in each organization

In each organization’s dashboard:

Navigate to Settings > Developers > Service Accounts
Create a service account with the corresponding public key
Save the authentication token securely

Assign appropriate permissions

Consider granting broader permissions in development for easier testing, while restricting production to the minimum required:

Environment	Recommended approach
Development	Broader permissions for rapid iteration
Staging	Match production permissions to catch issues
Production	Minimum 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:

Environment	Recommended storage
Development	Local `.env` file (gitignored)
Staging/Production	AWS 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:

Environment	Webhook URL
Development	`https://dev.example.com/webhooks/dfns` or local tunnel
Staging	`https://staging.example.com/webhooks/dfns`
Production	`https://api.example.com/webhooks/dfns`

For local development, use a tunneling service to receive webhooks on your local machine.

Create a service account

Step-by-step service account setup

Configure WebAuthn

Configure passkeys for multiple domains

Manage policies via API

Set up transaction policies

Set up webhooks

Configure event notifications

Introduction

Core Concepts

Platform Features

Networks

Solutions

Guides

Advanced

When to use multiple organizations

Setting up your organizations

Service accounts per environment

Recommended setup

Configuration management

Environment variables

Secrets management

Policies and permissions

Development environment

Staging environment

Production environment

Webhooks

Create a service account

Configure WebAuthn

Manage policies via API

Set up webhooks

​When to use multiple organizations

​Setting up your organizations

​Service accounts per environment

​Recommended setup

​Configuration management

​Environment variables

​Secrets management

​Policies and permissions

​Development environment

​Staging environment

​Production environment

​Webhooks

​Related

Create a service account

Configure WebAuthn

Manage policies via API

Set up webhooks

When to use multiple organizations

Setting up your organizations

Service accounts per environment

Recommended setup

Configuration management

Environment variables

Secrets management

Policies and permissions

Development environment

Staging environment

Production environment

Webhooks

Related