Getting started
Q: Where do I find my Organization ID, credentials, and auth token?
A: Here’s where to find each credential:- Organization ID — In the dashboard under Account settings. See Locating your organization ID.
- Service Account Token — Generated when you create a service account in the dashboard. It is shown once — save it securely.
- Credential ID — Listed in the dashboard under Settings > Developers, next to the key you registered.
- Private Key — The private key you generated locally (e.g., with OpenSSL) when setting up your service account. Dfns never stores this — only you have it.
Authentication
Q: Isn’t the signing secret you discuss the same thing as an API access key?
A: No, all calls to the Dfns API necessitate an API access key, which takes the form of a JWT (JSON Web Token), and must be provided in the authorization header as a Bearer token. This adherence to standard API security measures ensures that we validate this token for each request. On the other hand, we never possess the end user’s signing secret (also known as “API credentials”); our role is limited to verifying generated signatures. This guarantees that even if there were a bad actor within our own system, they would be unable to impersonate an end user and steal funds.Q: What’s the difference between Service Accounts and Personal Access Tokens?
A: Think of Service Accounts as analogous to a User Account designed for machine access. Similar to regular users, Service Accounts have individual permissions. On the other hand, personal access tokens are always linked to the user who generated them. They are incapable of having more permissions than their parent user, although they can have fewer permissions. If a user is disabled, all personal access tokens associated with that user are also disabled.Delegated Signing
Q: Where are your key shares stored today?
A: Key shares are encrypted and persisted in databases across multiple cloud regions and availability zones in T3+/T4 data centers. This geographic distribution helps to ensure reliable business continuity. We plan to decentralize this network further by contracting with highly secure, compliant and pre-vetted partners such as insurance companies, telecommunications companies, banks, private data centers, energy providers, etc.), to host key shares and sign transactions. This work is in progress.Q: Dfns holds the key shares — doesn’t that make you a custodian?
A: No. Dfns is a technical infrastructure provider, not a custodian. Custody is a legal and regulatory status with jurisdiction-specific definitions — it is not merely a technical concept. For instance, in the EU under the MiCA regulation, custodianship is determined by the ability to move assets on-chain. Dfns employees lack access to key shares and cannot use the API to impersonate clients or end-users, as they cannot provide a valid signature. Furthermore, Dfns in in the process of encapsulating its signers in AWS Nitro Enclaves to ensure key shares remain inaccessible, preventing collusion between engineers who operate within the network. Lastly, custodianship is also defined by contractual agreements between the key management solution and the client — the intentions outlined in these agreements often hold significant importance for regulators, sometimes even surpassing the significance of technical controls and guarantees.Q: Isn’t an end user wallet recovery code basically the same thing as a seed phrase?
A: No. With traditional wallets, a seed phrase recovers the wallet’s underlying private key — the key that directly controls the assets on-chain. If the seed phrase is compromised, those assets are gone. With Dfns, the wallet key is secured in the MPC network and never moves. What gets recovered is the user’s credential — the passkey used to authenticate and authorize actions. The wallet key and the credential are two separate things: the credential proves who you are, the wallet key signs transactions. Losing your credential doesn’t mean losing the wallet key; it means losing the ability to use it until you recover. When recovery is triggered, all existing credentials are invalidated, and the user registers a new passkey. Your application controls this flow and can add verification steps (identity checks, notifications, cooling periods) around the Dfns recovery API.Q: Can end-users export their private keys?
A: Users of Dfns wallets are never locked into the platform. They have the freedom to create a wallet using any other product or service and effortlessly transfer their assets out of Dfns using the API whenever they want. We also launched a private key export feature in 2023 which enables our Enterprise plan customers to export private keys to their users.Transactions
Q: Which endpoint should I use: Transfer, Sign & Broadcast, or Sign?
A: It depends on how much control you need:- Transfer API — Simplest option. Specify recipient, amount, and asset kind. Dfns builds, signs, and broadcasts the transaction. Use for standard sends (native coins, ERC-20, NFTs).
- Sign & Broadcast API — You construct the unsigned transaction (smart contract calls, DeFi interactions, etc.) and submit it. Dfns signs and broadcasts it. Use for anything beyond simple transfers.
- Sign API — Maximum control. Dfns only signs and returns the signed payload. You broadcast it yourself. Use when you need to manage broadcasting (private mempools, custom relay, etc.).
Q: What about listing transactions? What’s the difference between History, Transfers, and Transactions endpoints?
A: Each endpoint tracks different things:- Get Wallet History — Confirmed on-chain events only (both incoming and outgoing). Use for activity feeds and balance reconciliation.
- List Transfers — Outgoing Transfer API requests with full lifecycle (Pending → Confirmed/Failed/Rejected). Use to track transfers you initiated.
- List Transactions — Broadcast API requests with full lifecycle. Use to track custom transactions you submitted.
Confirmed status. See Transaction monitoring for details.
Common errors
Q: I’m getting “Monthly signatures limit reached”. What does this mean?
A: Your organization has exceeded the monthly signature quota for your current subscription plan. All signing operations (transfers, transactions, key signatures) count toward this limit, which resets each calendar month. Contact your account manager or support to upgrade to a higher tier.Q: I’m getting “Asset metadata not found” when transferring a token.
A: This 400 error means Dfns can’t find metadata for the asset you’re trying to transfer. Common causes:- The contract address or asset ID is incorrect for the target network
- The token was recently deployed and hasn’t been indexed yet — wait a few minutes and retry
- The asset doesn’t exist on the specified network