> ## Documentation Index
> Fetch the complete documentation index at: https://developer.coincover.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover encrypted backup data

> Recovers previously stored backup data. Requires successful identity verification (verification_id must be approved/successful). Requires a GPG public key for encrypting the recovered data. Returns an array of backup recovery results, each containing recovery information or error details. This endpoint calls the hot-keys orchestrator recover-backup endpoint for each backup associated with the user.



## OpenAPI

````yaml /specs/retail.openapi.json post /v1/backup/recover
openapi: 3.0.3
info:
  title: Control Orchestrator API
  description: API for orchestrating identity verification and key management workflows
  version: 1.0.0
servers:
  - url: https://orchestrator.control.coincover.com
    description: Production server
  - url: https://orchestrator.uat-control.coincover.com
    description: Development server
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Verification
    description: Start, check, and simulate biometric identity verification.
  - name: Keys
    description: Generate, assign, and verify cryptographic keys.
  - name: Backups
    description: Store and recover encrypted backup data.
paths:
  /v1/backup/recover:
    post:
      tags:
        - Backups
      summary: Recover encrypted backup data
      description: >-
        Recovers previously stored backup data. Requires successful identity
        verification (verification_id must be approved/successful). Requires a
        GPG public key for encrypting the recovered data. Returns an array of
        backup recovery results, each containing recovery information or error
        details. This endpoint calls the hot-keys orchestrator recover-backup
        endpoint for each backup associated with the user.
      operationId: recoverBackup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupRecoverRequest'
      responses:
        '200':
          description: Backup recovered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRecoverResponse'
              examples:
                gpg_algorithm:
                  summary: GPG encryption example
                  description: Example response using GPG encryption algorithm
                  value:
                    backup:
                      - backup_id: 550e8400-e29b-41d4-a716-446655440000
                        backup_item_key: seed_phrase
                        recovery_id: 660e8400-e29b-41d4-a716-446655440001
                        recovery_package:
                          algorithm: gpg
                          data: >-
                            LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tCkNpY2VsbGEgZGljdGEgc2VkIGVsZWlmZW5kLi4uCg==
                        original_filename: backup.json
                        content_type: application/json
                        original_size: '1024'
                rsa_direct_algorithm:
                  summary: RSA direct encryption example
                  description: >-
                    Example response using RSA-OAEP direct encryption for small
                    data
                  value:
                    backup:
                      - backup_id: 550e8400-e29b-41d4-a716-446655440000
                        backup_item_key: private_key
                        recovery_id: 660e8400-e29b-41d4-a716-446655440001
                        recovery_package:
                          algorithm: rsa-direct
                          data: >-
                            aGVsbG8gd29ybGQgdGhpcyBpcyBhIHNtYWxsIG1lc3NhZ2UgdGhhdCBjYW4gYmUgZW5jcnlwdGVkIGRpcmVjdGx5IHdpdGggUlNB
                        original_filename: key.txt
                        content_type: text/plain
                        original_size: '256'
                hybrid_algorithm:
                  summary: Hybrid RSA-AES256-GCM encryption example
                  description: >-
                    Example response using hybrid encryption (AES-256-GCM +
                    RSA-OAEP) for large data
                  value:
                    backup:
                      - backup_id: 550e8400-e29b-41d4-a716-446655440000
                        backup_item_key: wallet_config
                        recovery_id: 660e8400-e29b-41d4-a716-446655440001
                        recovery_package:
                          algorithm: hybrid-rsa-aes256-gcm
                          data: >-
                            dGhpcyBpcyBhIGxhcmdlIG1lc3NhZ2UgdGhhdCByZXF1aXJlcyBoeWJyaWQgZW5jcnlwdGlvbi4uLg==
                          encryptedKey: YWJjZGVmZ2hpams=
                          iv: MTIzNDU2Nzg5MGFi
                          tag: YWJjZGVmZ2hpams=
                        original_filename: wallet.json
                        content_type: application/json
                        original_size: '2048'
components:
  schemas:
    BackupRecoverRequest:
      type: object
      properties:
        user_identifier:
          type: string
          description: User identifier (REQUIRED)
          example: john.doe@example.com
        verification_id:
          type: string
          description: >-
            Verification ID from a successful verification. (REQUIRED) Must be
            approved/successful.
          example: inq_abc123xyz
        gpg_public_key:
          type: string
          description: >-
            GPG public key in PGP public key block format for encrypting the
            recovered data. (REQUIRED)
          example: |-
            -----BEGIN PGP PUBLIC KEY BLOCK-----
            ...
            -----END PGP PUBLIC KEY BLOCK-----
          pattern: >-
            ^-----BEGIN PGP PUBLIC KEY BLOCK-----[\s\S]*?-----END PGP PUBLIC KEY
            BLOCK-----$
      required:
        - user_identifier
        - verification_id
        - gpg_public_key
    BackupRecoverResponse:
      type: object
      properties:
        backup:
          type: array
          description: >-
            Array of recovered backup items. Each item contains recovery
            information or error details.
          items:
            $ref: '#/components/schemas/BackupRecoverItemResponse'
      required:
        - backup
    BackupRecoverItemResponse:
      type: object
      properties:
        backup_id:
          type: string
          format: uuid
          description: Unique identifier for the backup (UUID format). Always present.
          example: 550e8400-e29b-41d4-a716-446655440000
        backup_item_key:
          type: string
          description: >-
            Unique identifier for the backup item (e.g., "seed_phrase",
            "private_key", "wallet_config"). Present if available from metadata.
          example: seed_phrase
        recovery_id:
          type: string
          format: uuid
          description: ID of the recovery record. Present if recovery was successful.
          example: 660e8400-e29b-41d4-a716-446655440001
        recovery_package:
          $ref: '#/components/schemas/EncryptedDataSchema'
          description: >-
            Recovery package containing the recovered data in encrypted format.
            Present if recovery was successful. Supports multiple encryption
            algorithms: GPG, RSA direct, or hybrid RSA-AES256-GCM.
        original_filename:
          type: string
          description: >-
            Original filename of the backup. Present if recovery was successful
            and filename was stored.
          example: backup.json
        content_type:
          type: string
          description: >-
            Content type of the backup. Present if recovery was successful and
            content type was stored.
          example: application/json
        original_size:
          type: string
          description: >-
            Size of the original backup in bytes. Present if recovery was
            successful and size was stored.
          example: '1024'
        metadata:
          type: object
          description: Metadata associated with the backup. Present if metadata was stored.
          additionalProperties: true
        error:
          type: string
          description: Error message if recovery failed. Present only if recovery failed.
          example: Backup not found
      required:
        - backup_id
    EncryptedDataSchema:
      oneOf:
        - type: object
          description: GPG encryption/OpenPGP format
          properties:
            algorithm:
              type: string
              enum:
                - gpg
              description: 'Encryption algorithm: GPG encryption/OpenPGP'
              example: gpg
            data:
              type: string
              format: base64
              description: Base64-encoded encrypted data
              example: eyJhbGciOiJSU0EtT0FFUC1TSEEyNTYifQ...
          required:
            - algorithm
            - data
          additionalProperties: false
          example:
            algorithm: gpg
            data: >-
              LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tCkNpY2VsbGEgZGljdGEgc2VkIGVsZWlmZW5kLi4uCg==
        - type: object
          description: Direct RSA-OAEP encryption for small data
          properties:
            algorithm:
              type: string
              enum:
                - rsa-direct
              description: 'Encryption algorithm: Direct RSA-OAEP encryption for small data'
              example: rsa-direct
            data:
              type: string
              format: base64
              description: Base64-encoded encrypted data
              example: eyJhbGciOiJSU0EtT0FFUC1TSEEyNTYifQ...
          required:
            - algorithm
            - data
          additionalProperties: false
          example:
            algorithm: rsa-direct
            data: >-
              aGVsbG8gd29ybGQgdGhpcyBpcyBhIHNtYWxsIG1lc3NhZ2UgdGhhdCBjYW4gYmUgZW5jcnlwdGVkIGRpcmVjdGx5IHdpdGggUlNB
        - type: object
          description: 'Hybrid encryption: AES-256-GCM + RSA-OAEP for large data'
          properties:
            algorithm:
              type: string
              enum:
                - hybrid-rsa-aes256-gcm
              description: >-
                Encryption algorithm: Hybrid encryption (AES-256-GCM + RSA-OAEP)
                for large data
              example: hybrid-rsa-aes256-gcm
            data:
              type: string
              format: base64
              description: Base64-encoded encrypted data
              example: eyJhbGciOiJSU0EtT0FFUC1TSEEyNTYifQ...
            encryptedKey:
              type: string
              format: base64
              description: RSA-encrypted AES key (base64)
              example: rsa-encrypted-aes-key...
            iv:
              type: string
              format: base64
              description: AES-GCM initialization vector (base64, 12 bytes)
              example: initialization-vector...
            tag:
              type: string
              format: base64
              description: AES-GCM authentication tag (base64, 16 bytes)
              example: authentication-tag...
          required:
            - algorithm
            - data
            - encryptedKey
            - iv
            - tag
          additionalProperties: false
          example:
            algorithm: hybrid-rsa-aes256-gcm
            data: >-
              dGhpcyBpcyBhIGxhcmdlIG1lc3NhZ2UgdGhhdCByZXF1aXJlcyBoeWJyaWQgZW5jcnlwdGlvbi4uLg==
            encryptedKey: YWJjZGVmZ2hpams=
            iv: MTIzNDU2Nzg5MGFi
            tag: YWJjZGVmZ2hpams=
      discriminator:
        propertyName: algorithm
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication and authorization
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ID token as Bearer token

````