{"info":{"_postman_id":"9e318fdb-1522-47b7-93da-5b913d611afe","name":"CoinCover Recover - Aave","description":"

This document outlines the integration process for retail wallet providers looking to offer CoinCover Recover to their end users. By leveraging the Coincover Control Orchestrator API, this integration enables secure, identity-verified backup and recovery workflows.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"18877662","collectionId":"9e318fdb-1522-47b7-93da-5b913d611afe","publishedId":"2sBXVkCAGf","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-01-23T16:49:58.000Z"},"item":[{"name":"1. Authentication","item":[],"id":"10d97a8a-902e-436e-8058-e5908c1bb231","description":"

All requests require authentication via the header. The orchestrator supports two methods:

API Key: X-API-Key: [your_api_key]
\n
Bearer Token: Authorization: Bearer [your_api_key]
\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Environment	Base URL
Production	`https://orchestrator.control.coincover.com`
Development	`https://orchestrator.uat-control.coincover.com`

","_postman_id":"10d97a8a-902e-436e-8058-e5908c1bb231"},{"name":"2. Backup workflow","item":[],"id":"58764224-6ecf-47c0-b8fa-2efd525fe955","description":"

The backup phase links a user's identity with their encrypted data. While a backup can be initiated before verification is complete, a verification_id must be provided to associate the records.

\n\n

Step 1: Initialise verification

Call POST /v1/verification/start to generate a verification_id.

Pass this ID to your frontend to initialise the Persona SDK.
\n
Ensure you have a callback URL configured to receive status events (e.g., APPROVED, DECLINED).
\n

Request Schema

{  \n  \"user_identifier\": \"string (required)\"  \n}  \n\n

Response Schema

{  \n  \"verification_id\": \"string (Persona inquiry ID)\"  \n}  \n\n

Simulation & Testing

In non-production environments, you can use the x-override-status header to bypass manual verification steps and trigger specific webhook events or state change

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Name	Type	Description
`x-override-status`	`string`	Optional. Simulate a Persona outcome. (Sandbox only)

Accepted x-override-status values:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Value	Description
`start_inquiry`	Transitions inquiry to started state
`complete_inquiry`	Marks the inquiry as completed
`fail_inquiry`	Simulates a failed inquiry attempt
`expire_inquiry`	Simulates inquiry expiration
`mark_for_review_inquiry`	Moves inquiry to manual review status
`approve_inquiry`	Triggers an `APPROVED` outcome
`decline_inquiry`	Triggers a `DECLINED` outcome
`create_passed_verification`	Generates a successful verification record
`create_failed_verification`	Generates a failed verification record

Step 2: Generate cryptographic keys

Call POST /v1/key/generate to obtain the public key required for data encryption.

Required: user_identifier and the verification_id from Step 1.

Request Schema

{  \n  \"user_identifier\": \"string (required)\",  \n  \"verification_id\": \"string (required)\"  \n}  \n\n

Response Schema

{  \n  \"key_id\": \"string (UUID)\",  \n  \"public_key\": \"string (hex-encoded)\",  \n  \"signature\": \"string (base64)\"  \n}  \n\n

Step 3: Data encryption process

Before calling the store endpoint, you must encrypt the sensitive data client-side.

Get Public Key: Use the public_key returned in Step 2.
\n
Convert Format: Convert the hex-encoded public key to the appropriate format (PEM/DER) for your crypto library.
\n
Generate Checksum: Generate a SHA-256 checksum of the original, unencrypted data.
\n
Encrypt Data: Encrypt the data using RSA-OAEP with SHA-256 padding.
\n
Encode: Base64 encode the resulting ciphertext.
\n

Step 4: Store encrypted backup

Call POST /backup/store to persist the data.

Request schema

{  \n  \"user_identifier\": \"string (required)\",  \n  \"verification_id\": \"string (required)\",  \n  \"public_key\": \"string (hex-encoded, required)\",  \n  \"backup\": [  \n    {  \n      \"item_key\": \"string (required, e.g., 'seed_phrase')\",  \n      \"item_value\": \"string (base64, encrypted data)\",  \n      \"item_checksum\": \"string (SHA-256 hex of original data)\"  \n    }  \n  ],  \n  \"metadata\": {  \n    \"description\": \"string (optional)\",  \n    \"content_type\": \"string (optional)\",  \n    \"original_filename\": \"string (optional)\"  \n  }  \n}  \n\n

Response schema

{  \n  \"backup_type\": \"data\",  \n  \"metadata\": {  \n    \"stored_at\": \"string (ISO timestamp)\",  \n    \"backup_items_count\": \"integer\"  \n  },  \n  \"backup\": [  \n    {  \n      \"item_key\": \"string\",  \n      \"backup_id\": \"string (UUID)\",  \n      \"checksum\": \"string\",  \n      \"data_size\": \"integer\"  \n    }  \n  ]  \n}  \n\n

\n","_postman_id":"58764224-6ecf-47c0-b8fa-2efd525fe955"},{"name":"3. Recovery workflow","item":[],"id":"0e82704b-985f-47d2-82ff-d81fc8780fd2","description":"

Recovery is a restricted operation. Access to stored backups is only granted upon the presentation of a successful identity verification.

\n\n

Step 1: Re-verify identity

Call POST /v1/verification/start to begin a new recovery-specific session. Monitor the status via the configured webhook or the GET /v1/verification/status endpoint.

Response schema (GET /v1/verification/status)

{  \n  \"verification_id\": \"string\",  \n  \"status\": \"pending | approved | declined | review\",  \n  \"updated_at\": \"string (ISO timestamp)\"  \n}  \n\n

Step 2: Recover backup

Once the inquiry status is confirmed as APPROVED, call POST /v1/backup/recover.

GPG Key: A gpg_public_key must be provided in the request. The orchestrator uses this to encrypt the recovered data for transit.
\n
Authorisation: The orchestrator validates that the provided verification_id is successful and belongs to the user.
\n

Request schema

{  \n  \"user_identifier\": \"string (required)\",  \n  \"verification_id\": \"string (required, must be APPROVED)\",  \n  \"gpg_public_key\": \"string (PGP public key block format)\"  \n}  \n\n

Response schema

{  \n  \"user_identifier\": \"string\",  \n  \"verification_id\": \"string\",  \n  \"backup\": [  \n    {  \n      \"backup_id\": \"string (UUID)\",  \n      \"item_key\": \"string (e.g., 'seed_phrase')\",  \n      \"item_value\": \"string (base64, GPG encrypted data)\",  \n      \"item_checksum\": \"string (SHA-256 hex of the original unencrypted data)\",  \n      \"metadata\": {  \n        \"recovered_at\": \"string (ISO timestamp)\"  \n      }  \n    }  \n  ]  \n}  \n\n

Step 3: Rotation and re-backup

Following recovery, the new recovery code should be backed up using the POST /v1/backup/store endpoint to ensure the backup remains current.

\n
Note: A successful verification is valid for a limited window to perform recovery and subsequent re-stores.
\n

\n","_postman_id":"0e82704b-985f-47d2-82ff-d81fc8780fd2"},{"name":"4. Webhook & inquiry status","item":[],"id":"a2ea8d52-2ef5-49b9-a141-07be43f8802d","description":"

To provide a seamless user experience, your backend should implement a webhook listener to react to identity verification updates.

Source of truth

\n
Critical: Do not use client-side events from the Persona SDK for business logic or authorisation. SDK events are intended for UI transitions only and may not trigger if a user closes the browser prematurely. Always use webhook events for backend business logic.
\n

Webhook signature verification

All webhooks sent by the Control Orchestrator include a Coincover-Signature header. You must verify this signature to ensure the request originated from Coincover.

The signature is an HMAC-SHA256 hash calculated as: HMAC_SHA256(webhook_secret, \".\").

Signature Header Format:
t=1759929061,v1=bda09c34e8ee64000513f2ce47fa35e9b5376b2c691ad5e1475fc14d5804fd7f

Extract the timestamp (t=) and the signature (v1=).
\n
Concatenate the timestamp and the raw request body with a dot: timestamp.body.
\n
Compute the HMAC-SHA256 using your shared secret.
\n
Use a constant-time comparison (timingSafeEqual) to validate the computed hash against the v1 value.
\n

Inquiry outcomes

An inquiry transitions through several states. Recovery is only possible when the outcome is APPROVED.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description
CREATED	The inquiry has been initialised.
PENDING	The user is currently going through the IDV flow.
COMPLETED	The user has finished the flow, and data is being processed.
FAILED	An error occurred during the verification data collection process.
APPROVED	Verification Successful. Recovery operations are now authorized.
DECLINED	Data was collected successfully, but the automated IDV checks failed.
NEEDS_REVIEW	The inquiry is flagged for manual review by a compliance officer.
EXPIRED	The inquiry session timed out before completion.

","_postman_id":"a2ea8d52-2ef5-49b9-a141-07be43f8802d"}]}