Introduction

An API is available for all Silo users with Pooled Storage containers who would like to manage the content of those containers programmatically.  There are several interactions, detailed below, which are supported.


System Requirements

  • Pooled Storage.  The API calls are only supported for pooled storage containers.  Pooled storage is an add-on to the base Silo service.  Please see the Authentic8 Cloud Secure Storage documentation for more info.  Please contact your account manager (or sales@authentic8.com) for purchase details or to arrange a technical demo. 

  • API token.  Contact Support to obtain a token

  • Your pooled storage bucket_id.  Details on how to obtain this are below.

Details on API calls

Here is the list of supported file management requests:

  • Upload a file into A8 Secure Storage

  • Download files from A8 Secure Storage

  • Find files in A8 Secure Storage

  • Modify files in A8 Secure Storage

  • Delete files from A8 Secure Storage (updated)


Note: Secure Storage API is designed to work with Pooled storage containers only.  In addition, you will need to know the bucket id for the pooled storage containers that you intend to access with the API.  Read Authentic8 Cloud Secure Storage for more information.  


Uploading files

Files are uploaded by posting to an API URL (e.g., extapi.authentic8.com/putfile/).


Required parameters

  • bucket_id: bucket to place file into
  • name: name of file
  • file: file data
  • API endpoint


Optional parameters

  • path: where the file should be placed in the bucket’s directory structure. If not specified, ‘/’ is assumed.

  • content_type


Returns

 id of created file; e.g.:

{"file_id": "9806902c9cbea3820739c8ffb5331293"}


Example:

curl -F "auth=<file auth token>" -F "bucket_id=<desired bucket_id>" -F "name=my_file" -F "path=/my_directory" -F "file=@/tmp/my_file” https://extapi.authentic8.com/putfile/


Example output:

{

 "file_id": "f92f90d91cc80f77243b4461875c49bf"

}


Example audit log:

    {

      "username": "kevin", 

      "client_ip": "127.0.0.1", 

      "bucket_id": "3966f9e5412cf711bb6f92cc273393a0", 

      "user_id": "46671c19c5509efccdb7e906413673d4", 

      "name": "my_file", 

      "uploading_until": null, 

      "seq_id": 3907037, 

      "org_id": "50925dc546925170f877036d3b7820c0", 

      "bucket_type": "Pooled Storage", 

      "create_user": "46671c19c5509efccdb7e906413673d4", 

      "bucket_name": "shallow end", 

      "create_ts": "2016-11-04 18:20:41", 

      "content_type": "application/octet-stream", 

      "file_size": 241, 

      "action": "put file with external api", 

      "type": "A8SS", 

      "file_path": "/", 

      "file_id": "9806902c9cbea3820739c8ffb5331293"

    }


Downloading files

Files are downloaded by posting to an API URL (e.g., extapi.authentic8.com/getfile/).


Required parameters

  • file_id: unique file ID


Returns

requested file


Example usage:



curl -X POST -F "id=<desired File ID>" -F "auth=<URL encoded file auth token> https://extapi.authentic8.com/getfile/ -o <filename to save to>



Example audit log:

{

"username": "acardenas",

"bucket_type": "User Storage",

"bucket_id": "4ec26bca9804e16ac079f7c2c14ca96c",

"user_id": "e92a9e35c318b86d7d82131ba2fbbb5d",

"name": "SamplePPTX.pptx",

"org_id": "53ba4d41358a7f599d106eed140cb8b0",

"client_ip": "10.1.2.3",

"create_user": "e92a9e35c318b86d7d82131ba2fbbb5d",

"bucket_name": "My Drive",

"file_id": "11cc183d638672ad904d78f02e9af689",

"content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",

"file_size": 413895,

"action": "get file with external api",

"type": "A8SS",

"file_path": "/",

"create_ts": "2016-11-21 22:22:51"

}


Finding files

This is a standard json-format command.  


Command name: findfiles


Required parameters

  • bucket_id


Optional parameters

  • name: filter by file name

  • path: filter by path

  • type: filter by object type (file, directory)

  • :name_starts_with: boolean parameter; specify that ‘name’ parameter should match the beginning of file name entries. Requires ‘name’ parameter to be present.

  • :name_contains: boolean parameter; specify that ‘name’ parameter should be present in file name entries. Requires ‘name’ parameter to be present.

  • :created_before : filter for files with create timestamps before this

  • :created_before_or_at : filter for files with create timestamps before or equal to this

  • :created_after : filter for files with create timestamps after this

  • :created_after_or_at : filter for files with create timestamps after or equal to this


Notes

  • the “:created…” fields take iso8601 strings (e.g., 2016-11-01T18:19:11.265006), epoch time (e.g., 1478127958), or “now+<seconds>”. To specify a time in the past by relative offset, use “now+-<seconds>”.

  • If you omit “path”, you get a full-bucket search.

  • The filters are treated as “and”

  • You must POST the JSON to the endpoint, https://extapi.authentic8.com/api/


Example call:

[
  {

    "command": "setauth",
"data": "<auth token>"
},
  {

    "command": "findfiles",
"bucket_id": "3966f9e5412cf711bb6f92cc273393a0",
":created_after": "now+-5"
}
]


Example return:

[

    {

        "result": "setting auth from data"

    },

    {

        "result": [

            {

                "bucket_id": "3966f9e5412cf711bb6f92cc273393a0",

                "content_type": "application/octet-stream",

                "create_ts": "2016-11-04T18:20:40.851985",

                "expire_ts": null,

                "file_id": "3486e12ebd7ab8666615126ee3d49599",

                "file_size": 241,

                "name": "my_file",

                "path": "/",

                "type": "file",

                "uploading_until": null

            }

        ]

    }

]


No audit logs are generated by this method.


Modifying files

This is a standard json-format command.


Command name: modifyfile


Required parameters

  • file_id


Optional parameters

  • content_type

  • name

  • path

  • expire_ts


expire_ts formats

  • iso8601 string (e.g., 2016-11-01T18:19:11.265006)

  • epoch time (e.g., 1478127958)

  • now+<seconds> : offset from current time (seconds may be negative)

  • +<seconds> : offset from existing expire time (seconds may be negative)

  • reset: set file expire to default bucket expire time. For example, if the bucket has a 90-day default expire, “reset” would set the file’s expiration time to 90 days in the future, as though it had just been created.

Note


Example call:

[
  {

    "command": "setauth",
"data": "<auth token>"
},
  {

    "command": "modifyfile",
"name": "newname",
"expire_ts": "now+3600",
"file_id": "b5ea33ed8762698c629db9fc17e26c5e"
}
]


Example return:

[

    {

        "result": "setting auth from data"

    },

    {

        "result": "update file b5ea33ed8762698c629db9fc17e26c5e [expire_ts, name]"

    }

]


Example audit log:

    {

      "username": "kevin", 

      "bucket_type": "Pooled Storage", 

      "user_id": "46671c19c5509efccdb7e906413673d4", 

      "new_values": {

        "name": "newname", 

        "expire_ts": "2016-11-04T19:20:42.593791", 

        "uploading_until": null, 

        "bucket_id": "3966f9e5412cf711bb6f92cc273393a0", 

        "create_ts": "2016-11-04T18:20:40.851985", 

        "content_type": "application/octet-stream", 

        "file_size": 241, 

        "path": "/", 

        "type": "file", 

        "file_id": "3486e12ebd7ab8666615126ee3d49599"

      }, 

      "org_id": "50925dc546925170f877036d3b7820c0", 

      "client_ip": "127.0.0.1", 

      "bucket_id": "3966f9e5412cf711bb6f92cc273393a0", 

      "file_id": "3486e12ebd7ab8666615126ee3d49599", 

      "old_values": {

        "name": "oldname", 

        "expire_ts": null, 

        "uploading_until": null, 

        "bucket_id": "3966f9e5412cf711bb6f92cc273393a0", 

        "create_ts": "2016-11-04T18:20:40.851985", 

        "content_type": "application/octet-stream", 

        "file_size": 241, 

        "path": "/", 

        "type": "file", 

        "file_id": "3486e12ebd7ab8666615126ee3d49599"

      }, 

      "seq_id": 3907038, 

      "action": "modify file with external api", 

      "type": "A8SS", 

      "create_ts": "2016-11-04 18:20:42"

    }



Deleting Files

This is a standard json-format command.


This method parallels the pre-existing api-host/deletefile API endpoint. It was added for consistency (in that JSON-formatted commands handle all non-bulk-transfer API activity), and so that multiple files can be deleted with a single API call. It is otherwise unremarkable.


Command name: deletefile


Required parameters

  • File_id


Notes on Deleting Files


There are no optional parameters for this API method.


Example call:

[
  {

    "command": "setauth",
"data": "<auth token>"
},
{
"command": "deletefile",
"file_id": "c1396149c1982c246c5a7d719080ce89"
}
]


Example return:

[

    {

        "result": "setting auth from data"

    },

    {

        "result": "deleted file c1396149c1982c246c5a7d719080ce89"

    }

]


Example audit log:

    {

      "username": "kevin", 

      "client_ip": "127.0.0.1", 

      "bucket_id": "3966f9e5412cf711bb6f92cc273393a0", 

      "user_id": "46671c19c5509efccdb7e906413673d4", 

      "name": "newname", 

      "uploading_until": null, 

      "seq_id": 3907039, 

      "org_id": "50925dc546925170f877036d3b7820c0", 

      "bucket_type": "Pooled Storage", 

      "create_user": "46671c19c5509efccdb7e906413673d4", 

      "bucket_name": "shallow end", 

      "create_ts": "2016-11-04 18:20:43", 

      "content_type": "application/octet-stream", 

      "file_size": 241, 

      "action": "delete file with external api", 

      "type": "A8SS", 

      "file_path": "/", 

      "file_id": "3486e12ebd7ab8666615126ee3d49599"

}

    

Notes

  • All API calls require a FIle Auth Token which can be obtained from Authentic8 Support.

  • All Secure Storage API calls are supported in Pooled Storage only.  Temporary Storage and user storage are not supported at this time. 


Additional Notes  

Please contact Support if you have any additional questions and/or require further information.