API.md

Hush API

Hush is a dead-simple, no-frills credentials management and secure storage vault. It aims to be secure, stable, and simple, in that order.

Vault Operations

To query the status of the Vault:

GET /v1/sys/status HTTP/1.1
Accept: application/json

{
  "version" : "1.23.45",
  "locked"  : true,
  "guid"    : "6f207303-e75b-4cb2-8ced-2b5c337e4373",
  "name"    : "James' Vault"
}

To lock the Vault:

POST /v1/lock HTTP/1.1

200 OK

To unlock the Vault:

POST /v1/unlock HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "key": "secret-key"
}

200 OK
Content-Type: application/json
Content-Length: ...

{
  "ok"        : "key accepted",
  "shares" : {
    "required"    : 5,
    "met"         : 1,
    "outstanding" : 4
  }
}

To abort an in-progress unlock attempt:

DELETE /v1/unlock HTTP/1.1

200 OK

Filesystem Operations

Hush is built around a virtual filesystem where directories (folders) contain other directories and secrets.

To retrieve a single secret:

GET /v1/fs/PATH/TO/THE/SECRET HTTP/1.1

200 OK
Content-Type: application/json
Content-Length: ...

{
  "type"        : "leaf",
  "version"     : 1,
  "created-at"  : 1234567,
  "modified-at" : 1234567,
  "value": {
    "user-key" : "user-value"
  }
}

To create / update a secret:

PUT /v1/fs/PATH/TO/THE/SECRET HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "new-user-key": "new-user-value"
}

200 OK
Content-Type: application/json
Content-Length: ...

{
   "ok"      : "updated (or created)",
   "version" : 2
}

To remove a secret:

DELETE /v1/fs/PATH/TO/THE/SECRET HTTP/1.1

200 OK

To list a directory:

GET /v1/fs/PATH/TO/DIR/SUB HTTP/1.1

200 OK
Content-Type: application/json
Content-Length: ...

{
  "type": "interior",
  "entries": [
    "FILE",
    "OTHER",
    "DIR/"
  ]
}

To list a directory (recursively):

GET /v1/fs/PATH/TO/DIR?recurse=yes HTTP/1.1

200 OK
Content-Type: application/json
Content-Length: ...

{
  "type": "interior",
  "tree": {
     "SUB/": {
        "FILE"  : 0,
        "OTHER" : 1,
        "DIR/": {
          "FILE"  : 2
        }
     }
  },
  "entries" : [
    "SUB/FILE",
    "SUB/OTHER",
    "SUB/DIR/FILE"
  ]
}

To remove a directory (recursively):

DELETE /v1/fs/PATH/TO/DIR?recurse=yes HTTP/1.1

200 OK

To copy a credential:

POST /v1/ops/copy/ROOT/PATH
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "from" : "REL/PATH/TO/COPY/FROM"
  "to"   : "REL/PATH/TO/COPY/TO"
}

To copy a directory (recursively):

POST /v1/ops/copy/ROOT/PATH?recurse=yes
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "from" : "REL/PATH/TO/COPY/FROM"
  "to"   : "REL/PATH/TO/COPY/TO"
}

To rename a credential:

POST /v1/ops/rename/ROOT/PATH
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "from" : "REL/PATH/TO/RENAME/FROM"
  "to"   : "REL/PATH/TO/RENAME/TO"
}

To rename a directory (recursively):

POST /v1/ops/rename/ROOT/PATH?recurse=yes
Accept: application/json
Content-Type: application/json
Content-Length: ...

{
  "from" : "REL/PATH/TO/RENAME/FROM"
  "to"   : "REL/PATH/TO/RENAME/TO"
}

Summarize a subset of the fs store:

GET /v1/summary/PATH/TO/SUMMARIZE HTTP/1.1
Accept: application/json

{
  "paths".     : 42,
  "attributes" : 91
}