Note To be more precise, it's not the request itself which needs to be signed, but it's actually a "User Action Challenge" issued by Dfns which needs to be signed. As a simplification, we speak of "request signing"

This request signature is a cryptographic proof that you and only you are making the request. Without it, the request would raise an Unauthorized error.

Credentials can be one of two kinds (check our API docs Credential section for more details): WebauthN Credentials or Key Credentials. WebauthN credentials only work in the browser. Key credentials are server-side only (AsymmetricKeySigner). The classes below support each one, their responsibility is to sign a challenge:

Browser Signer

The SDK exposed in @dfns/sdk-browser implements WebAuthnSigner.

`WebAuthnSigner`

WebAuthnSigner implements CredentialSigner and CredentialStore. It needs to be used client-side (on a browser, in a web-app)

import { WebAuthnSigner } from '@dfns/sdk-browser'

const webauthn = new WebAuthnSigner({ relyingParty: { id: 'acme.com', name: 'Acme' } })

React Native Signer

PasskeysSigner in @dfns/sdk-react-native package, implements CredentialSigner and CredentialStore. It needs to be used client-side with the react native framework.

import { PasskeysSigner } from '@dfns/sdk-react-native'

const passkeys = new PasskeysSigner()

`AsymmetricKeySigner`

AsymmetricKeySigner in @dfns/sdk-keysigner package, implements CredentialSigner. It needs to be used server-side only — a key sitting in browser memory is unsafe. In a browser, use WebAuthnSigner.

import { AsymmetricKeySigner } from '@dfns/sdk-keysigner'

const keySigner = new AsymmetricKeySigner({
  credId: 'X2ktMzhxaTEtZTF1bTgtOXY1cG9yY2tkZDe1dG1jYg', // Credential ID
  privateKey: process.env.DFNS_PRIVATE_KEY!, // Credential private key
})

credId: ID of the Credential registered with the auth token you’re using (Personal Access Token, or Service Account Token). In Dfns dashboard, you can find it next to your token (in Settings > My Access Tokens or Settings > Service Accounts)
privateKey: private key (in .pem format) which only you have, associated with the public key you registered when you created your PAT / Service Account.

`DfnsApiClient`

DfnsApiClient is the main Dfns client, holding most supported functionalities of Dfns API.

It needs to be authenticated, so DfnsApiClient needs to be passed a valid authToken. This authToken can be:

a Service Account token - long-lived
a User Personal Access Token (PAT) - long-lived
a User token issued after on User login - expires

DfnsApiClient also needs to be passed a CredentialSigner, in order to sign requests.

import { DfnsApiClient } from '@dfns/sdk'

const signer = ... // a Credential Signer (webauthN or key signer from section above)

const apiClient = new DfnsApiClient({
  baseUrl: 'https://api.dfns.io', // base Url of DFNS API
  orgId: 'or-2ng9jv-80cfc-983pop0iauf2sv8r', // ID of the Dfns Organisation
  authToken: '...', // an auth token
  signer,
})

// create a wallet
const wallet = await dfns.wallets.createWallet({
    body: { network: 'EthereumSepolia' }
})

// get assets in wallet
const { assets } = await dfns.wallets.getWalletAssets({ walletId: wallet.id })

Deployments behind a path prefix

baseUrl may include a gateway path, for example https://platform.example.com/api. A request to /wallets then uses https://platform.example.com/api/wallets; a trailing slash on the base URL is optional. The gateway must strip the prefix before forwarding to the API. Base URLs containing a query string or fragment are rejected.

The SDK signs the canonical API route without the gateway prefix. Client-generated challenges retain the route's query string; server-generated challenges use its pathname.

`DfnsDelegatedApiClient`

In some configurations, you might want your server to be the one talking to Dfns "on behalf of the user", but till have the user sign all requests (on a web-app, using the WebauthN Credentials he owns). In this case, the DfnsDelegatedApiClient can be used on your server.

The difference with the above DfnsApiClient is:

In DfnsApiClient, all steps to sign the request are done internally.
In DfnsDelegatedApiClient, the signing of the request (of the challenge, really) happens outside of it. So while the request can be conducted by the server, the signature of this request can be done by the User (on a web-app).

In a way, DfnsDelegatedApiClient "delegates" request signing outside of it. As a result:

Its constructor does not need a CredentialSigner (since signing happens outside)
Every method requiring signing (eg dfns.wallets.createWallet()) will be split in two methods:
- dfns.wallets.createWalletInit(): takes in the request payload, and returns a challenge that should be signed by a CredentialSigner.
- dfns.wallets.createWalletComplete(): takes in the request payload + the signed challenge, and completes the wallet creation.

An example flow would look like:

The Server executes createWalletInit, and sends back the returned challenge to the use on the web-app.
In the web-app, the User signs the challenge (using WebauthN signer), and sends the signed challenge to the server.
The server uses the User signed challenge to createWalletComplete on behalf of the user.

import { DfnsDelegatedApiClient } from '@dfns/sdk'

const dfnsDelegated = new DfnsDelegatedApiClient({
  baseUrl: 'https://api.dfns.io', // base Url of DFNS API
  orgId: 'org-2ng9jv-80cfc-983pop0iauf2sv8r', // ID of the Dfns Organisation
  authToken: userAuthToken, // Auth token of the User
})

const challenge = await dfnsDelegated.wallets.createWalletInit(payload)

// ... the server can now send this challenge to the user, so the User signs it with his credentials

// ... Later, after user sends back the signed challenge, the server can complete the request:

const wallet = await dfnsDelegated.wallets.createWalletComplete(payload, signedChallenge)

`DfnsAuthenticator`

In a client-side app, if you want a Dfns User to be able to login with Dfns (and get an auth token back), you might wanna use DfnsAuthenticator:

import { DfnsAuthenticator } from '@dfns/sdk'
import { WebAuthn } from '@dfns/sdk-browser'

const dfnsAuth = new DfnsAuthenticator({
  orgId,
  baseUrl: apiUrl,
  signer: new WebAuthn({ rpId }),
})

// Since we are using a Webauthn Signer here, this will prompt the user for webauthn credentials (touch id / phone id / yubikey touch...)
const { token } = await dfnsAuth.login({ orgId, username })

`BaseAuthApi`

BaseAuthApi is a Dfns client which holds some special auth-related Dfns methods (some of them are un-authenticated API endpoints for login/registration) which might get handy.

import { BaseAuthApi } from '@dfns/sdk/baseAuthApi'

BaseAuthApi.createUserActionChallenge()
BaseAuthApi.signUserActionChallenge()
BaseAuthApi.createUserLoginChallenge()
BaseAuthApi.createUserLogin()
BaseAuthApi.createUserRegistrationChallenge()
BaseAuthApi.createUserRegistration()

Platform Integrations

Integrations with other blockchain platforms to make Dapp development frictionless. More to come...