> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Delegated Recovery Challenge
>
Only a [Service Account](https://docs.dfns.co/api-reference/auth/service-accounts) can use this endpoint.
Starts a recovery session for an end user under your brand, without sending a Dfns recovery email. Call this after you have verified the user's identity with your own auth system.
The response returns a recovery challenge. Pass it to your frontend so the user can decrypt their recovery credential and sign, then call [Recover User](https://docs.dfns.co/api-reference/auth/recover-user) to complete the recovery and register fresh credentials.
#### Authentication
❌ Organization User (`CustomerEmployee`)\
❌ Delegated User (`EndUser`)\
✅ Service Account
#### Required Permissions
`Auth:Recover:Delegated`: Always required.
## OpenAPI
````yaml /openapi.yaml post /auth/recover/user/delegated
openapi: 3.1.0
info:
version: 1.891.1
title: Dfns
servers:
- url: https://api.dfns.io
description: Default - Europe
- url: https://api.uae.dfns.io
description: UAE
- url: https://api.dfns.ninja
description: Staging
security: []
paths:
/auth/recover/user/delegated:
post:
tags:
- Auth
summary: Create Delegated Recovery Challenge
description: >
Only a [Service
Account](https://docs.dfns.co/api-reference/auth/service-accounts) can
use this endpoint.
Starts a recovery session for an end user under your brand, without
sending a Dfns recovery email. Call this after you have verified the
user's identity with your own auth system.
The response returns a recovery challenge. Pass it to your frontend so
the user can decrypt their recovery credential and sign, then call
[Recover User](https://docs.dfns.co/api-reference/auth/recover-user) to
complete the recovery and register fresh credentials.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
minLength: 1
description: Username/identifier of the user to recover.
credentialId:
type: string
minLength: 1
description: Identifier of the recovery credential to use.
required:
- username
- credentialId
additionalProperties: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
id:
type: string
description: Base64url-encoded user handle (WebAuthn user.id).
displayName:
type: string
description: Display name of the user.
name:
type: string
description: Username of the user.
required:
- id
- displayName
- name
temporaryAuthenticationToken:
type: string
description: >-
JWT used to identify the registration session when calling
Complete User Registration.
challenge:
type: string
description: Challenge to be signed by the credential being registered.
rp:
type: object
properties:
id:
type: string
description: >-
ID of the WebAuthn relying party (typically a domain
name).
name:
type: string
description: Human-readable name of the relying party.
required:
- id
- name
description: Deprecated. Should not be used.
supportedCredentialKinds:
type: object
properties:
firstFactor:
type: array
items:
type: string
enum:
- Fido2
- Key
- Password
- Totp
- RecoveryKey
- PasswordProtectedKey
description: Credential kinds accepted as first factor.
secondFactor:
type: array
items:
type: string
enum:
- Fido2
- Key
- Password
- Totp
- RecoveryKey
- PasswordProtectedKey
description: Credential kinds accepted as second factor.
required:
- firstFactor
- secondFactor
description: Credential kinds that can be used to register the user.
authenticatorSelection:
type: object
properties:
authenticatorAttachment:
type: string
enum:
- platform
- cross-platform
residentKey:
type: string
enum:
- required
- preferred
- discouraged
requireResidentKey:
type: boolean
userVerification:
type: string
enum:
- required
- preferred
- discouraged
description: >
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
required:
- residentKey
- requireResidentKey
- userVerification
attestation:
type: string
enum:
- none
- indirect
- direct
- enterprise
description: >
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
pubKeyCredParams:
type: array
items:
type: object
properties:
type:
type: string
enum:
- public-key
alg:
type: number
required:
- type
- alg
description: >-
Public key credential parameters supported for the
registration.
excludeCredentials:
type: array
items:
type: object
properties:
type:
type: string
enum:
- public-key
description: Is always `public-key`.
id:
type: string
minLength: 1
maxLength: 64
pattern: ^cr-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$
description: ID that identifies the credential.
example: cr-6uunn-bm6ja-f6rmod5kqrk5rbel
required:
- type
- id
description: >-
Credentials to exclude from the registration (already
registered for the user).
otpUrl:
type: string
description: URL to provision a TOTP credential, when applicable.
allowedRecoveryCredentials:
type: array
items:
type: object
properties:
id:
type: string
description: Identifier of the recovery credential.
encryptedRecoveryKey:
type: string
description: >-
Encrypted recovery key associated with this
credential.
required:
- id
- encryptedRecoveryKey
additionalProperties: false
required:
- user
- temporaryAuthenticationToken
- challenge
- supportedCredentialKinds
- authenticatorSelection
- attestation
- pubKeyCredParams
- excludeCredentials
- otpUrl
- allowedRecoveryCredentials
additionalProperties: false
security:
- authenticationToken: []
userActionSignature: []
components:
securitySchemes:
authenticationToken:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
**Bearer Token:** Used to authenticate API requests.
More details how to generate the token: [Authentication
flows](https://docs.dfns.co/api-reference/auth/login-flows)
userActionSignature:
type: apiKey
in: header
name: X-DFNS-USERACTION
description: >-
**User Action Signature:** Used to sign the change-inducing API
requests.
More details how to generate the token: [User Action Signing
flows](https://docs.dfns.co/api-reference/auth/signing-flows)
````