.. _create_object:

Method: Create Objects
----------------------

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

Create a new Object in an existing Vault.

A user can create (update, or delete) objects in a Vault, if the
following conditions are met:

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

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

/api/{version}/object

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

POST

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

200

Parameters
~~~~~~~~~~

+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| Parameter name |                 Description                 | Parameter type |  Type  | Mandatory |            Comment             |
+================+=============================================+================+========+===========+================================+
| X-Http-Token   | StoredSafe token                            | HTTP Header    | String | :sup:`1)` | Preferred method               |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| token          | StoredSafe token                            | JSON-encoded   | String | :sup:`1)` | Legacy method                  |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| templateid     | Template-ID                                 | JSON-encoded   | String | Yes       |                                |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| groupid        | Vault-ID                                    | JSON-encoded   | String | Yes       |                                |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| parentid       | Parent-ID                                   | JSON-encoded   | String | Yes       |                                |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| objectname     | Name of Object                              | JSON-encoded   | String | Yes       |                                |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| host           | Name of host (from template)                | JSON-encoded   | String | Yes       | Depends on template being used |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| username       | Username (from template)                    | JSON-encoded   | String | Yes       | Depends on template being used |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| info           | Additional unencrypted info (from template) | JSON-encoded   | String | Yes       | Depends on template being used |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| password       | Password (from template)                    | JSON-encoded   | String | Yes       | Depends on template being used |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+
| cryptedinfo    | Additional encrypted info (from template)   | JSON-encoded   | String | Yes       | Depends on template being used |
+----------------+---------------------------------------------+----------------+--------+-----------+--------------------------------+

\*) One of the methods (HTTP Header or JSON-encoded) 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.objectid   | Assigned Object-ID                              | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.status     | SUCCESS or FAIL                                 | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.message    | Any 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  |
+---------------------+-------------------------------------------------+---------+
| PARAMS              | PARAMS (empty)                                  | Array   |
+---------------------+-------------------------------------------------+---------+

Examples
~~~~~~~~

Create a new object in Vault-ID 179 using Template-id 1 (A Server
template).

**Request**

::

    POST /api/1.0/object
    x-http-token: your_storedsafe_token
    {
        "templateid": "1",
        "groupid": "179",
        "parentid": "0",
        "objectname": "firewall2.za.example.com",
        "host": "firewall2.za.example.com",
        "username": "root",
        "info": "The second pfSense fw protecting the ZA branch.",
        "password": "~[vN8x9W6~7P367vm53Y",
        "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O"
    }

**Response**

::

    HTTP/2 200
    Content-type: application/json; charset=UTF-8
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [
                "BAD_POLICY"
            ],
            "handler": "ObjectHandler",
            "message": "Object successfully saved",
            "objectid": 1368,
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": {
            "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O",
            "groupid": "179",
            "host": "firewall2.za.example.com",
            "info": "The second pfSense fw protecting the ZA branch.",
            "objectname": "firewall2.za.example.com",
            "parentid": "0",
            "password": "~[vN8x9W6~7P367vm53Y",
            "templateid": "1",
            "token": "your_storedsafe_token",
            "username": "root"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Content-Length": "304",
            "Content-Type": "application/x-www-form-urlencoded",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1",
            "X-Http-Token": "your_storedsafe_token"
        },
        "PARAMS": []
    }