.. _download_files:

Method: Download Files
----------------------

Description
~~~~~~~~~~~

Retrieve all open (not encrypted) data regarding a File Object, as well as the
contents of the file encoded in Base64.

A user can retrieve a File Object in a Vault, if the
following conditions are met:

*  The user has been assigned Read permission in the Vault by the Data
   Custodian (a user with the Admin capability) of the Vault.

URL Syntax
~~~~~~~~~~

/api/{version}/object

HTTP Method
~~~~~~~~~~~

GET

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+------------------+----------------+---------+-----------+-----------------------+
| Parameter name |   Description    | Parameter type |  Type   | Mandatory |        Comment        |
+================+==================+================+=========+===========+=======================+
| X-Http-Token   | StoredSafe token | HTTP Header    | String  |           |                       |
+----------------+------------------+----------------+---------+-----------+-----------------------+
| object-id      | Object ID        | URL-parameter  | Integer | Yes       |                       |
+----------------+------------------+----------------+---------+-----------+-----------------------+
| filedata       | Download content | URL-parameter  | Boolean | Yes       | Should be set to true |
+----------------+------------------+----------------+---------+-----------+-----------------------+

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------------------+----------------------------------------------------------------+---------+
|            Attribute            |                          Description                           |  Type   |
+=================================+================================================================+=========+
| FILEDATA                        | Base64-encoded contents of file                                | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| BREADCRUMB                      | Breadcrumb                                                     | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| BREADCRUMB.icon                 | Icon used                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| BREADCRUMB.objectid             | Object-ID                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| BREADCRUMB.objectname           | Object name                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| 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.message                | Message from handler (if successful)                           | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.token                  | StoredSafe token to be used in subsequent calls                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| HEADERS                         | HTTP Headers                                                   | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| DATA                            | Supplied data in API-call                                      | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT                          | OBJECT entry                                                   | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.id                       | Object-ID                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.parentid                 | Parent-ID                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.templateid               | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.groupid                  | Vault-ID                                                       | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.status                   | Status (Active, Follows policy)                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.objectname               | Name of object                                                 | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.filename                 | Filename                                                       | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.children                 | Any children                                                   | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.notes                    | Encrypted notes                                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.tags                     | Tags associated with the object                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.alarmed                  | Should an alarm sound if object is decrypted?                  | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.public                   | Public data (Depends on Template used, see supplied TEMPLATES) | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.crypted                  | Decrypted data (If decrypt is True) Depends on Template        | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES                       | TEMPLATES (Glue) Used templates in the vault                   | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.id                    | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.id               | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.name             | Name of template                                               | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.ico              | Icon used for template                                         | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.active           | Active (True/False)                                            | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.wb               | Use workbench for edit? (Always use "ed" if false.             | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.ed               | Edit directly? (no subitems)                                   | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.jp               | Jump to parent on save?                                        | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure             | Template Structure                                             | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.translation | Descriptive text (english)                                     | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.type        | Type of element (text, textarea, text-passwdgen, file)         | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.encrypted   | Is field encrypted?                                            | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.fieldname   | Identifier of field                                            | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.show        | Show field normally or only in workbench?                      | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.policy      | Should field honor Vaults password policy?                     | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.alarm       | Should alarm sound if object is decrypted?                     | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.opt         | Is this an optional field or is it required to be filled?      | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.cc          | Needs to be changed to be considered unseen?                   | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.nc          | Encrypted fields needs to be clicked to be revealed?           | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| PARAMS                          | PARAMS (empty)                                                 | Array   |
+---------------------------------+----------------------------------------------------------------+---------+

Examples
~~~~~~~~

Retrieve all information, including file contents of Object-ID 63f8d06437b26deabfa16.

**Request**

::

    GET /api/1.0/object/63f8d06437b26deabfa16?filedata=true
    x-http-token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    {
        "OBJECT": [
            {
                "fileinfo": {
                    "objectid": "63f8d06437b26deabfa16",
                    "name": "hello.txt",
                    "size": "13",
                    "type": "text/plain",
                    "filepath": "/opt/storedsafe/upload/63f8d0644a47905345e32_63f8d06437b26deabfa16.enc",
                    "created": "2023-02-24 15:57:40",
                    "ext": "txt",
                    "iconpath": "/img/ico/mime/txt.png"
                },
                "id": "63f8d06437b26deabfa16",
                "parentid": "0",
                "templateid": "3",
                "groupid": "6319fd25876b469c76164",
                "status": "128",
                "objectname": "",
                "filename": "hello.txt",
                "children": "0",
                "notes": false,
                "tags": "",
                "alarmed": false,
                "public": {
                    "file1": "",
                    "description": ""
                }
            }
        ],
        "TEMPLATES": [
            {
                "id": "3",
                "info": {
                    "id": "3",
                    "name": "File",
                    "ico": "ico_file",
                    "active": true,
                    "wb": true,
                    "jp": true,
                    "file": "*"
                },
                "structure": [
                    {
                        "translation": "File",
                        "type": "file",
                        "encrypted": false,
                        "show": true,
                        "policy": false,
                        "alarm": false,
                        "opt": false,
                        "cc": false,
                        "nc": false,
                        "fieldname": "file1"
                    },
                    {
                        "translation": "Description",
                        "type": "text",
                        "encrypted": false,
                        "show": true,
                        "policy": false,
                        "alarm": false,
                        "opt": true,
                        "cc": false,
                        "nc": false,
                        "fieldname": "description"
                    }
                ]
            }
        ],
        "BREADCRUMB": [
            {
                "objectid": "63f8d06437b26deabfa16",
                "objectname": "hello.txt",
                "icon": "ico_file"
            }
        ],
        "FILEDATA": "SGVsbG8sIEZpbGUhCg==",
        "DATA": {
            "filedata": "true",
            "decrypt": "false",
            "token": "your_storedsafe_token"
        },
        "HEADERS": {
            "X-Http-Token": "your_storedsafe_token",
            "Accept": "*/*",
            "User-Agent": "curl/7.81.0",
            "Host": "safe.domain.cc"
        },
        "PARAMS": [],
        "CALLINFO": {
            "token": "rotated_storedsafe_token",
            "general": [],
            "handler": "ObjectHandler",
            "status": "SUCCESS",
            "errors": 0,
            "errorcodes": 0
        }
    }