Credentials API data

Client Data

The Client Data object is used during user registration, new credential creation, login, recovery and action signing

Fido2 credential

When using Fido2, the client data object is built inside the authenticator and returned to the browser base64url encoded. There is no need to modify it. More information can be found in the W3C webauthn offical specification

field	type	description
type	`string`	`webauthn.create` for registration and new credential `webauthn.get` for login and action signing
challenge	`string`	The challenge returned from the init call
origin	`string`	The origin in which the app is being executed
crossOrigin	`boolean`	A flag indicating if the current call is running cross origin; in most cases this should be `false`

Example

// Client data as returned by the authenticator during registration
eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiWTJndE16bGxORFl0YUdKdGRtMHRPR3gwY1hFemMybzBPRGczWlRkd09BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0

// Client data object
{
  "type":"webauthn.create",
  "challenge":"Y2gtMzllNDYtaGJtdm0tOGx0cXEzc2o0ODg3ZTdwOA",
  "origin":"https://app.dfns.ninja",
  "crossOrigin":false
}

Key, Password Protected Key and Recovery credential

Unlike when using Fido2 credential, the client data object needs to be created manually for Key credential. Once created the object needs to be “stringified” and base64url encoded.

Critical formatting requirements:

Keys must be alphabetically sorted (e.g., challenge before type)
JSON separators must have no spaces after : and ,
The result must be base64url encoded (not standard base64)

Incorrect formatting will cause “Unable to verify signature” errors.

// Define keys in alphabetical order - JSON.stringify preserves insertion order
const clientData = {
  challenge: challenge,  // 'c' comes before 't'
  type: 'key.get'
};
const clientDataJson = JSON.stringify(clientData);
// Result: '{"challenge":"...","type":"key.get"}'
const clientDataBase64url = Buffer.from(clientDataJson).toString('base64url');

// Define keys in alphabetical order - JSON.stringify preserves insertion order
const clientData = {
  challenge: challenge,  // 'c' comes before 't'
  type: 'key.get'
};
const clientDataJson = JSON.stringify(clientData);
// Result: '{"challenge":"...","type":"key.get"}'
const clientDataBase64url = Buffer.from(clientDataJson).toString('base64url');

import json
import base64

client_data = {"type": "key.get", "challenge": challenge}
# Use separators to remove whitespace and sort_keys to order alphabetically
client_data_json = json.dumps(client_data, separators=(',', ':'), sort_keys=True)
# Result: '{"challenge":"...","type":"key.get"}'
client_data_base64url = base64.urlsafe_b64encode(client_data_json.encode()).decode().rstrip('=')

field	type	description
type	`string`	`key.create` for registration and new credential `key.get` for login and action signing
challenge	`string`	The challenge returned from the init call. The challenge is already base64url encoded, there is no need to encode it

Example

// Client data object
{
  "challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw",
  "type":"key.create"
}

// Stringify
'{"challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw","type":"key.create"}'

// Base64url
eyJjaGFsbGVuZ2UiOiJZMmd0Tnpsb2FIUXRiWEpsYjJzdE9HRndPSEZ0TW1WcFpXWjBhbXhoWnciLCJ0eXBlIjoia2V5LmNyZWF0ZSJ9

Attestation Data

This attestation data object is used during registration and new credential.

Fido2 credential

When using Fido2, the attestation data object is built inside the authenticator and returned to the browser. It is encoded using CBOR specification. There is no need to modify it. More information can be found in the W3C webauthn offical specification. It is an opaque object and there is no need to describe it here.

Example

// Attestation Data as returned by the authenticator during registration
o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZjc2lnWEcwRQIgVHg5PQ_mEyPi_FRZdkgT-SXmspljVaOWJBcN3M0iDxoCIQC8dJkvMWREoJrEdgECSRWzUxXG0WbrpCiajYEJ8mNF5mN4NWOBWQLdMIIC2TCCAcGgAwIBAgIJANVbnGiXosqIMA0GCSqGSIb3DQEBCwUAMC4xLDAqBgNVBAMTI1l1YmljbyBVMkYgUm9vdCBDQSBTZXJpYWwgNDU3MjAwNjMxMCAXDTE0MDgwMTAwMDAwMFoYDzIwNTAwOTA0MDAwMDAwWjBvMQswCQYDVQQGEwJTRTESMBAGA1UECgwJWXViaWNvIEFCMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMSgwJgYDVQQDDB9ZdWJpY28gVTJGIEVFIFNlcmlhbCAxNzU1MDc3NTg5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAQap0H_qWf7Lo9-qH8Xj2q-EtN-D_jO0JWxfoyafAdQRcIHIhUMixqtqB9fd5M95L0F4zS7Pvbe5EIA_tns7naOBgTB_MBMGCisGAQQBgsQKDQEEBQQDBQQDMCIGCSsGAQQBgsQKAgQVMS4zLjYuMS40LjEuNDE0ODIuMS43MBMGCysGAQQBguUcAgEBBAQDAgUgMCEGCysGAQQBguUcAQEEBBIEEO6IKHlyHEkTl3U9_M6XByowDAYDVR0TAQH_BAIwADANBgkqhkiG9w0BAQsFAAOCAQEAhDTK-uoXyNUKvzPk-mTjRykakGfJx6CXWJHJAR_zdkHQHaNA-SB8z3a2lmn9sBKI2_-9T3Pasj4gaaXiQxqOXbifp8Iv5nz7rKtmmMuur_u4-XMkOo-wLdZvcjwj-jWdX0daFGmRU0Yck4tYw6-Y_hJ_L8mNT_Odu2jqY3--WlZ8T9H-c9BYhz3dG1MCiQpYH_tw5sz0LXuSFrM3tF_0yEehgtwDwANby9OG7KqUf7O0ArvpBcFFPj8lJf_1_6qXkwFSYxZZzKXHwNsumEdpB7is-X6M4sWG_dcl6msj-hQdtWpxokCWzymdlUG5mk541vtzqpMjM6UvREg1wWjoXmhhdXRoRGF0YVjCtP0s4DAIslfywtetyFg4YfWUmc3GcqHTevk0O6OswibFAAAAAe6IKHlyHEkTl3U9_M6XByoAMEmPqgPRjx312Ywh4gex7TgWLwE2kWRNFGsBomlOLuGIceqoSXgbyAXJgksJs_8_nqUBAgMmIAEhWCBJj6oD0Y8d9dmMIeIHCSUgwKr6FKqaytOhNxEZnGoOYiJYIPGzFTyHoPed-ysej7WwkaaHydkatYmz0rInky2TzyiKoWtjcmVkUHJvdGVjdAI

// CBOR decoded Attestation Data
{
  "authData" : {
    "rpIdHash" : "tP0s4DAIslfywtetyFg4YfWUmc3GcqHTevk0O6OswiY=",
    "flags" : -59,
    "signCount" : 1,
    "attestedCredentialData" : {
      "aaguid" : {
        "value" : "ee882879-721c-4913-9775-3dfcce97072a",
        "bytes" : "7ogoeXIcSROXdT38zpcHKg=="
      },
      "credentialId" : "SY+qA9GPHfXZjCHiB7HtOBYvATaRZE0UawGiaU4u4Yhx6qhJeBvIBcmCSwmz/z+e",
      "cosekey" : {
        "1" : "2",
        "3" : -7,
        "-1" : 1,
        "-2" : "SY+qA9GPHfXZjCHiBwklIMCq+hSqmsrToTcRGZxqDmI=",
        "-3" : "8bMVPIeg9537Kx6PtbCRpofJ2Rq1ibPSsieTLZPPKIo=",
        "1" : 2
      }
    },
    "extensions" : {
      "credProtect" : 2
    },
    "flagUP" : true,
    "flagUV" : true,
    "flagAT" : true,
    "flagED" : true
  },
  "attStmt" : {
    "alg" : -7,
    "sig" : "MEUCIFR4OT0P5hMj4vxUWXZIE/kl5rKZY1WjliQXDdzNIg8aAiEAvHSZLzFkRKCaxHYBAkkVs1MVxtFm66Qomo2BCfJjReY=",
    "x5c" : [ "MIIC2TCCAcGgAwIBAgIJANVbnGiXosqIMA0GCSqGSIb3DQEBCwUAMC4xLDAqBgNVBAMTI1l1YmljbyBVMkYgUm9vdCBDQSBTZXJpYWwgNDU3MjAwNjMxMCAXDTE0MDgwMTAwMDAwMFoYDzIwNTAwOTA0MDAwMDAwWjBvMQswCQYDVQQGEwJTRTESMBAGA1UECgwJWXViaWNvIEFCMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMSgwJgYDVQQDDB9ZdWJpY28gVTJGIEVFIFNlcmlhbCAxNzU1MDc3NTg5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAQap0H/qWf7Lo9+qH8Xj2q+EtN+D/jO0JWxfoyafAdQRcIHIhUMixqtqB9fd5M95L0F4zS7Pvbe5EIA/tns7naOBgTB/MBMGCisGAQQBgsQKDQEEBQQDBQQDMCIGCSsGAQQBgsQKAgQVMS4zLjYuMS40LjEuNDE0ODIuMS43MBMGCysGAQQBguUcAgEBBAQDAgUgMCEGCysGAQQBguUcAQEEBBIEEO6IKHlyHEkTl3U9/M6XByowDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAQEAhDTK+uoXyNUKvzPk+mTjRykakGfJx6CXWJHJAR/zdkHQHaNA+SB8z3a2lmn9sBKI2/+9T3Pasj4gaaXiQxqOXbifp8Iv5nz7rKtmmMuur/u4+XMkOo+wLdZvcjwj+jWdX0daFGmRU0Yck4tYw6+Y/hJ/L8mNT/Odu2jqY3++WlZ8T9H+c9BYhz3dG1MCiQpYH/tw5sz0LXuSFrM3tF/0yEehgtwDwANby9OG7KqUf7O0ArvpBcFFPj8lJf/1/6qXkwFSYxZZzKXHwNsumEdpB7is+X6M4sWG/dcl6msj+hQdtWpxokCWzymdlUG5mk541vtzqpMjM6UvREg1wWjoXg" ]
  },
  "fmt" : "packed"
}

Key, Password Protected Key and Recovery credential

Unlike when using Fido2 credential, the attestation data object needs to be created manually for Key credential. Once created the object needs to be “stringified” and base64url encoded. Before building the attestation data object, the credential info fingerprint object needs to be created.

Credential Info Fingerprint

The attestation data object contains a signature. This section explains how to construct the credential info fingerprint object that is then signed and included in the attestation data object.

Field	Type	Description
`clientDataHash`	string	The hex encoded SHA-256 hash of the “stringified” client data object
`publicKey`	string	PEM encoded public key that can be used to verify the signature for the credential

In order for the server to properly verify the signature, the clientDataHash needs to be computed in a reproducible way. That means the “stringified” operation of the client data object needs to be done with the following requirements:

Keys need to be sorted in alphabetical order: challenge first, and then type
Separators need to be : and , without any space before and after

For example given the following client data object

{
  "challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw",
  "type":"key.create"
}

The “stringified” version needs to be

{"challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw","type":"key.create"}

Example

// Client data object
{
  "challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw",
  "type":"key.create"
}

// "Stringified" client data
{"challenge":"Y2gtNzloaHQtbXJlb2stOGFwOHFtMmVpZWZ0amxhZw","type":"key.create"}

// SHA256 hex encoded
cba00cc2224e76aa12e42cd0e30a1a73e5525ed0dccb7e29e709fee3a1e98dec

// Credential info fingerprint object
{
  "clientDataHash": "cba00cc2224e76aa12e42cd0e30a1a73e5525ed0dccb7e29e709fee3a1e98dec",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n"
}

So the attestation data object is built with the following fields

Field	Type	Description
`publicKey`	string	PEM encoded public key that can be used to verify the signature for the credential. This the same public key than the one in the Credential Info Fingerprint object
`signature`	string	The signature produced by signing the “stringified” Credential Info Fingerprint object with the credentials private key, using the algorithm specified in `algorithm`. Needs to be encoded as a hex string
`algorithm`	string	`Optional` The algorithm/digest that the credential will use to sign data. If the algoritm is not specified the algorithm will be determined by the key. Can be one of the following choices: `RSA-SHA256` `SHA256` `SHA512`

In order for the server to properly verify the signature, the “stringified” operation of the Credential Info Fingerprint object needs to be done with the following requirements:

Keys need to be sorted in alphabetical order: clientDataHash first, then publicKey
Separators need to be : and , without any space before and after

For example given the following client data object

{
  "clientDataHash": "cba00cc2224e76aa12e42cd0e30a1a73e5525ed0dccb7e29e709fee3a1e98dec",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n"
}

The “stringified” version needs to be

{"clientDataHash":"cba00cc2224e76aa12e42cd0e30a1a73e5525ed0dccb7e29e709fee3a1e98dec","publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n"}

The signature also needs to be generated with pre-defined hash algorithm and encoding:

Hash algorithm: SHA256
Encoding: DER. See Signature Format for more information

Signing Example

// Keys must be in alphabetical order
const clientData = {
  challenge: challenge,  // 'c' before 't'
  type: 'key.create',
}

const clientDataJson = JSON.stringify(clientData)
const signaturePayload = JSON.stringify({
  clientDataHash: crypto.createHash('sha256').update(clientDataJson).digest('hex'),
  publicKey: newKey.publicKey,  // 'c' before 'p'
})
const signature = crypto.sign(undefined, Buffer.from(signaturePayload), newKey.privateKey)

Example

// Hex encoded signature of the string '{"clientDataHash":"cba00cc2224e76aa12e42cd0e30a1a73e5525ed0dccb7e29e709fee3a1e98dec","publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n"}'
30460221008e0109848c6fc83004d0e6c7fdac71dae8524fc5a29081d012f865416986ce29022100f47e1bee6c5175c4488b143c936c68fac1ae7e7931e76c677d46331ed149d17d

// Attestation Data object
{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n",
  "signature": "30460221008e0109848c6fc83004d0e6c7fdac71dae8524fc5a29081d012f865416986ce29022100f47e1bee6c5175c4488b143c936c68fac1ae7e7931e76c677d46331ed149d17d"
}

// Stringify
'{"publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9cG2mE4DWHbwwlLRSKBLZ9m6+QsC\neOqWJh1x5VvRHZMaPLQlRrhhgbHm8una4h8S+L5o8sV8Hvujbl3MrATj3Q==\n-----END PUBLIC KEY-----\n","signature":"30460221008e0109848c6fc83004d0e6c7fdac71dae8524fc5a29081d012f865416986ce29022100f47e1bee6c5175c4488b143c936c68fac1ae7e7931e76c677d46331ed149d17d"}'

// Base64url
eyJwdWJsaWNLZXkiOiAiLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRTljRzJtRTREV0hid3dsTFJTS0JMWjltNitRc0NcbmVPcVdKaDF4NVZ2UkhaTWFQTFFsUnJoaGdiSG04dW5hNGg4UytMNW84c1Y4SHZ1amJsM01yQVRqM1E9PVxuLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tXG4iLCJzaWduYXR1cmUiOiIzMDQ2MDIyMTAwOGUwMTA5ODQ4YzZmYzgzMDA0ZDBlNmM3ZmRhYzcxZGFlODUyNGZjNWEyOTA4MWQwMTJmODY1NDE2OTg2Y2UyOTAyMjEwMGY0N2UxYmVlNmM1MTc1YzQ0ODhiMTQzYzkzNmM2OGZhYzFhZTdlNzkzMWU3NmM2NzdkNDYzMzFlZDE0OWQxN2QifQ

API Authorization

Identity & Access Management

Wallets & Transactions

Management

Webhooks

Client Data

Fido2 credential

Example

Key, Password Protected Key and Recovery credential

Example

Attestation Data

Fido2 credential

Example

Key, Password Protected Key and Recovery credential

Credential Info Fingerprint

Signing Example

Example

​Client Data

​Fido2 credential

​Example

​Key, Password Protected Key and Recovery credential

​Example

​Attestation Data

​Fido2 credential

​Example

​Key, Password Protected Key and Recovery credential

​Credential Info Fingerprint

​Signing Example

​Example

Client Data

Fido2 credential

Example

Key, Password Protected Key and Recovery credential

Example

Attestation Data

Fido2 credential

Example

Key, Password Protected Key and Recovery credential

Credential Info Fingerprint

Signing Example

Example