.. _backup_key: Method: Backup Key ------------------ Description ~~~~~~~~~~~ This endpoint returns a plaintext backup of a named key. The backup contains all information needed to restore the key (and all it's versions) to another vault, or another StoredSafe instance, using the :ref:`/restore` endpoint. .. note:: The key must be set to :ref:`allow_backup` to support this operation. .. note:: This endpoint requires :ref:`Admin` permission in the affected vault. URL Syntax ~~~~~~~~~~ /api/{version}/transparent/backup/:vaultid/:name HTTP Method ~~~~~~~~~~~ GET Successful HTTP Response ~~~~~~~~~~~~~~~~~~~~~~~~ 200 Parameters ~~~~~~~~~~ +----------------+------------------+----------------+--------+---------+-----------+------------------+ | Parameter name | Description | Parameter type | Type | Default | Mandatory | Comment | +================+==================+================+========+=========+===========+==================+ | X-Http-Token | StoredSafe token | HTTP Header | String | | :sup:`1)` | Preferred method | +----------------+------------------+----------------+--------+---------+-----------+------------------+ | token | StoredSafe token | JSON-encoded | String | | :sup:`1)` | Legacy method | +----------------+------------------+----------------+--------+---------+-----------+------------------+ | vaultid | Vault-ID | URL-encoded | String | | Yes | | +----------------+------------------+----------------+--------+---------+-----------+------------------+ .. note:: :sup:`1)` One of the methods is required. Response Attributes ~~~~~~~~~~~~~~~~~~~ +---------------------+------------------------------------+---------+ | Attribute | Description | Type | +=====================+====================================+=========+ | CALLINFO.errorcodes | Number of errors | Integer | +---------------------+------------------------------------+---------+ | CALLINFO.errors | Number of errors | Integer | +---------------------+------------------------------------+---------+ | CALLINFO.general | Information | Array | +---------------------+------------------------------------+---------+ | CALLINFO.handler | Handler used | String | +---------------------+------------------------------------+---------+ | CALLINFO.status | SUCCESS or FAIL | String | +---------------------+------------------------------------+---------+ | CALLINFO.token | Rotated StoredSafe token :sup:`1)` | String | +---------------------+------------------------------------+---------+ | CALLINFO.version | Key version | String | +---------------------+------------------------------------+---------+ | CALLINFO.objectid | Object-ID | String | +---------------------+------------------------------------+---------+ | KEYS | Keys | Array | +---------------------+------------------------------------+---------+ | KEYS.backup | Backup of key | String | +---------------------+------------------------------------+---------+ | DATA | Supplied data in prior API-call | String | +---------------------+------------------------------------+---------+ | HEADERS.(headers) | HTTP Headers | String | +---------------------+------------------------------------+---------+ | PARAMS | Route parameters (empty) | Array | +---------------------+------------------------------------+---------+ | ERRORCODES | Error code and text :sup:`2)` | Object | +---------------------+------------------------------------+---------+ | ERRORS | Error code and text :sup:`2)` | Array | +---------------------+------------------------------------+---------+ .. note:: | :sup:`1)` Token to be used in subsequent calls | :sup:`2`) Only present if errors Examples ~~~~~~~~ Obtain a backup of the named key ``my-new-key`` used for transparent encryption in the vault (vault-id) 179. **Request** :: GET /api/1.0/transparent/backup/179/my-new-key x-http-token: your_storedsafe_token **Response** :: HTTP/2 201 Content-type: application/json; charset=UTF-8 { "CALLINFO": { "errorcodes": 0, "errors": 0, "general": [], "handler": "EncryptionHandler", "status": "SUCCESS", "token": "rotated_storedsafe_token" }, "KEYS": { { "backup": "nE5hpsaXES36QB057qUeED6EKMbzfbjiy+g2BiZ1yIYJH/1Nv3w76vVZpj2F3Ln3Y77tx6VIuoFAOz5OA+hB+jQYCdqYTBelwFcrklML6nNuPv1XZ1EVKprWOGrheqBZ4j2BB0ScXkS+VzguFQrCpc+CxpzI5WtDnxmbMbkJZLU=", }, }, "DATA": { "name": "my-new-key", "token": "your_storedsafe_token", }, "HEADERS": { "Accept": "*/*", "Content-Length": "169", "Content-Type": "application/json", "Host": "safe.domain.cc", "User-Agent": "curl/7.64.1", "X-Http-Token": "your_storedsafe_token" }, "PARAMS": [] }