Create Credential Challenge

POST /auth/credentials/init

Part of the flow Create Credential Regular flow.

Starts a create user credential session, returning a challenge that will be used to verify the user's identity.

• Request headers required. See Request Headers for more information.

• Authentication required. See Authentication Headers for more information.

Required Permissions

The permissions apply to the application only.

Name	Conditions
Auth:Creds:Create	Always Required

Request body

kind *	String	The kind of credential being added to the user's account; can be Fido2, Key, PasswordProtectedKey or RecoveryKey (see Credential Kind)

{
  "kind": "Fido2"
}

Responses

• See Common Errors for common errors.

• See Credential Management Errors for credential management specific errors.

200

Success - an object containing the user's authentication options

Format:

{
  // the kind of credential being created
  "kind": "string",
  // Challenge Identifier
  "challengeIdentifier": "string",
  // random value used to uniquely identify the request. This value will be included in the data that is signed
  "challenge": "string",
  // Relying Party information that identifies the application to the user
  "rp": {
    // the domain of the server that is requesting the credential. This must match the effective domain of the application communicating with the user's WebAuthn client
    "id": "string",
    // a user friendly name to help identify the server requesting the credential
    "name": "string",
  },
  // identifies the user that is being logged into the Dfns API
  "user": {
    // id that ties the user to the credential created in the user's WebAuthn client
    "id": "string",
    // additional value that will be displayed to the user on the WebAuthn client's display
    "name": "string",
    // name that will be displayed to the user on the WebAuthn client's display
    "displayName": "string"
  },
  // list of objects that identify the signing algorithms that are supported
  "pubKeyCredParam": [
    {
      // will always be `public-key`
      "type": "public-key",
      // an integer that identifies a signing algorithm. Can be either `-7` for ES256 or `-257` for RS256
      "alg": "number"
    },
  ],
  // identifies the information needed to verify the user's signing certificate; can be one of the following:
  // * none: indicates no attestation data is required
  // * indirect: indicates the attestation data should be given, but that it can be generated using an Anonymization CA
  // * direct: indicates the attestation data must be given and should be generated by the authenticator
  // * enterprise: indicates the attestation data should include information to uniquely identify the user's device
  "attestation": "string",
  // a list of objects that identify credentials that the user's WebAuthn client should not use
  "excludeCredentials": [
    {
      // will always be `public-key`
      "type": "public-key",
      // ID that can identify the credential on the authenticator
      "id": "string",
      // types of transports that are not allowed. Can be one of the following:
      // * usb for usb support
      // * nfc for near field communication (NFC) support
      // * ble for bluetooth support
      // * internal for non-removable authenticators
      // * hybrid for multiple transport methods
      "transports": "string"
    }
  ],
  // identifies the criteria that the user's WebAuthn client should use when creating the credential
  "authenticatorSelection": {
    // optional value indicating the type of authenticators that are supported. If not set then the authenticator type is not restricted. Can be one of the following:
    // * platform for requiring the authenticator be tied to the users device (like a TPM)
    // * cross-platform for the authenticator to be an external device (like a Yubikey)
    "authenticatorAttachment": "string",
    // value indicating whether or not the authenticator should use resident keys. Can be one of the following:
    // * discouraged to indicate the authenticator should not use a resident key unless its the only option
    // * preferred to indicate the authenticator should try to use a resident key if supported
    // * required to indicate the authenticator must use a resident key
    "residentKey": "required",
    // value indicating if the authenticator needs to support resident keys
    "requireResidentKey": "boolean",
    // value indicating if the user should be prompted for a second factor. Can be one of the following values:
    // * required to indicate the user must be prompted for their pin, biometrics, or another second factor option
    // * preferred to indicate the user should be prompted for a second factor if it is supported
    // * discouraged to indicate the user should not be prompted for their second factor unless the device requires it
    "userVerification": "required"
  }
}

Example

{
  "kind": "Fido2",
  "challengeIdentifier": "eyJ0eXAiOiJKV1Q...X1bwCg35kbzsjA",
  "challenge": "MmE5YzRmMzMwY2NlNGUyMjhjZWYzMzlhZDBhZmIxNzk",
  "rp": {
    "id": "dfns.io",
    "name": "Dfns",
  },
  "user": {
    "id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
    "name": "[e-mail]",
    "displayName": "[e-mail]"
  },
  "pubKeyCredParam": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "attestation": "direct",
  "excludeCredentials": [],
  "authenticatorSelection": "",{
    "residentKey": "required",
    "requireResidentKey": true,
    "userVerification": "required"
  }
}