gopass/docs/jsonapi.md

JSON API

Overview

The API follows the specification for native messaging from Mozilla and Chrome. Each JSON-UTF8 encoded message is prefixed with a 32-bit integer specifying the length of the message. Communication is performed via stdin/stdout.

WARNING: This API MUST NOT be exposed over the network to remote hosts. No authentication is performed and the only safe way is to communicate via stdin/stdout as you do in your terminal.

The implementation is located in utils/jsonapi.

Request Types

query

Query:

{
  "type": "query",
  "query": "secret"
}

Response:

[
    "somewhere/mysecret/loginname",
    "somewhere/else/secretsauce"
]

queryHost

Similar to query but cuts hostnames and subdomains from the left side until the response to the query is non-empty. Stops if only the public suffix is remaining.

Query:

{
  "type": "queryHost",
  "host": "some.domain.example.com"
}

Response:

[
    "somewhere/domain.example.com/loginname",
    "somewhere/other.domain.example.com"
]

getLogin

Query:

{
   "type": "getLogin",
   "entry": "somewhere/else/secretsauce"
}

Response:

{
   "username": "hugo",
   "password": "thepassword"
}

create

Query:

{
   "type": "create",
   "login": "myusername",
   "password": "",
   "length": 12,
   "generate": true,
   "use_symbols": true
}

Response:

{
   "username": "myusername",
   "password": "5^dX9j1\"b5^q"
}

Error Response

If an uncaught error occurs, the stringified error message is send back as the response:

{
  "error": "Some error occurred with fancy message"
}