Import Key

Dfns secures private keys by generating them as MPC key shares in our decentralized key management network. This happens by default when you create a key or wallet.

In some circumstances, however, you may need to import an existing private key into Dfns infrastructure, instead of creating a brand new wallet with Dfns and transfer funds to it. As an example, you might want to keep an existing wallet if its address is tied to a smart contract which you don’t want to re-deploy.

In such a case, Dfns exposes this key import API endpoint, which can be used in conjunction with our import SDK. Note this is intended to be used only to migrate wallets when first onboarding onto the Dfns platform.

Dfns can not guarantee the security of imported wallets, as we have no way to control who had access to the private key prior to import. For this reason, this feature is restricted to Enterprise customers who have signed a contractual addendum limiting our liability for imported keys. Please contact your sales representative for more information.

POST /keys/import

Import Key

cURL

curl --request POST \
  --url https://api.dfns.io/keys/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-DFNS-USERACTION: <api-key>' \
  --data '
{
  "curve": "ed25519",
  "protocol": "CGGMP24",
  "minSigners": 123,
  "encryptedKeyShares": [
    {
      "signerId": "<string>",
      "encryptedKeyShare": "<string>"
    }
  ],
  "name": "<string>",
  "masterKey": true
}
'

200

{
  "id": "key-01snl-t56gb-j8tsok0vn802p80i",
  "scheme": "ECDSA",
  "curve": "ed25519",
  "publicKey": "<string>",
  "status": "Active",
  "custodial": true,
  "dateCreated": "2023-04-14T20:41:28.715Z",
  "masterKey": true,
  "derivedFrom": {
    "keyId": "key-01snl-t56gb-j8tsok0vn802p80i",
    "path": "<string>"
  },
  "name": "<string>",
  "imported": true,
  "exported": true,
  "dateExported": "2023-04-14T20:41:28.715Z",
  "dateDeleted": "2023-04-14T20:41:28.715Z"
}

Authentication

✅ Organization User (CustomerEmployee)
✅ Delegated User (EndUser)
✅ Service Account

Required Permissions

Keys:Import: Always required.

Authorizations

Authorization · string · header · required

Bearer Token: Used to authenticate API requests. More details how to generate the token: Authentication flows

X-DFNS-USERACTION · string · header · required

User Action Signature: Used to sign the change-inducing API requests. More details how to generate the token: User Action Signing flows

Body

application/json

curve · enum<string> · required

Available options: ed25519, secp256k1, stark

protocol · Option 1 · enum<string> Option 2 · enum<string> · required

Available options: CGGMP24, FROST, FROST_BITCOIN, GLOW20_DH, KU23

minSigners · integer · required

encryptedKeyShares · object[] · required

Minimum array length: 1

Show child attributes

name · string

Maximum string length: 100

masterKey · boolean

Specify to create an extended master key for HD derivation

Response

200 - application/json

Success

id · string · required

Unique identifier for the key.

Required string length: 1 - 64

Example:

"key-01snl-t56gb-j8tsok0vn802p80i"

scheme · enum<string> · required

The cryptographic scheme for the key.

Available options: ECDSA, EdDSA, Schnorr

curve · enum<string> · required

The elliptic curve for the key.

Available options: ed25519, secp256k1, stark

publicKey · string · required

Hex-encoded public key.

status · enum<string> · required

Current status of the key.

Available options: Active, Archived

custodial · boolean · required

Whether the key is custodial (owned by organization) or non-custodial (delegated to end user).

dateCreated · string<date-time> · required

ISO 8601 date (must be UTC). When the key was created.

Example:

"2023-04-14T20:41:28.715Z"

masterKey · boolean

Whether this key can be used as a master key for HD derivation.

derivedFrom · object

Derivation info if this key was derived from a master key.

Show child attributes

name · string

Nickname for the key.

imported · boolean

Whether this key was imported.

exported · boolean

Whether this key has been exported.

dateExported · string<date-time>

ISO 8601 date (must be UTC). When the key was exported.

Example:

"2023-04-14T20:41:28.715Z"

dateDeleted · string<date-time>

ISO 8601 date (must be UTC). When the key was deleted.

Example:

"2023-04-14T20:41:28.715Z"