Passbolt API Documentation

Introduction

This document describes passbolt server component API. The API works over HTTPS in a REST fashion, so it is language framework agnostic. You can integrate passbolt services into your existing workflow using the toolset of your choice.

Getting Started

To get started with the passbolt REST API (hereafter referred to as “The API”) you need at least:

• A running passbolt server instance.
• A passbolt user account if you want to access protected data.
• Some basic understanding of how public key cryptography works.
• An OpenPGP-compliant library to build with.

Base URL

The API is served over HTTPS. All URLs referenced in the documentation omit the base url of your passbolt installation domain such as: https://<passbolt.your-organization.com>.

Response format

Response envelope

The API returns data in an envelope with “header” and “body” properties. The “header” contains response metadata like response code, server_time, error messages etc. The “body” contains the actual payload.

For example, requesting a single resource by id will result in something like:

{
    "header": {
        "id": "799c69c7-1789-4d87-9fbf-02529b0d21dc",
        "status": "success",
        "servertime": 1554909967,
        "action": "ad71952e-7842-599e-a19e-3a82e6974b23",
        "message": "The operation was successful.",
        "url": "\/secrets\/resource\/8e3874ae-4b40-590b-968a-418f704b9d9a.json",
        "code": 200
    },
    "body": {
        "id": "eede75ff-316a-511c-8317-51e8339b6dcc",
        "user_id": "f848277c-5398-58f8-a82a-72397af2d450",
        "resource_id": "8e3874ae-4b40-590b-968a-418f704b9d9a",
        "resource_type_id": "e2aa01a9-84ec-55f8-aaed-24ee23259339",
        "data": "-----BEGIN PGP MESSAGE-----",
        "created": "2019-04-04T12:06:50+00:00",
        "modified": "2019-04-04T12:06:50+00:00"
    }
}

Error responses

An unsuccessful operation will result in an error response. The error response will follow the same scheme as above with the presence of both “header” and “body” properties, only this time the status in the header will be set to error instead of success. The response body will contain the error details.

{
    "header": {
        "id": "965c9f17-18ae-48fd-a36e-e42f04a30442",
        "status": "error",
        "servertime": 1554907648,
        "action": "ad8bbc35-6435-538e-b1a7-80b87bcedb6a",
        "message": "Could not validate resource data.",
        "url": "\/resources.json",
        "code": 400
    },
    "body": {
        "name": {
            "_required": "A name is required."
        },
        "secrets": {
            "_required": "A secret is required."
        }
    }
}

As you can see, for validation errors, the response body contains two keys, “name” and “secrets” as they failed some validation rules. Further, they also have their own json object with a key (“_required”) that represents the validation rule that failed and a value with the actual error message (“A name is required”).

API Versions

Historically, passbolt supported two different formats for interacting with the API. API version 1 is now deprecated. The passbolt server component supports only API version 2 and all calls are assumed to be version 2 - no parameter is needed to designate this.

You can see the complete changelog on the official the repository.

Encryption and decryption

Security and privacy are the biggest concerns for a password manager and passbolt is no exception. Passbolt’s solution uses end-to-end encryption and the encryption and decryption is always done on the client. The server is mainly used to take care of relational data integrity and storage.

Passbolt uses public key cryptography and OpenPGP specifically. This guide will assume you are familiar with these concepts.

fig. password exchange using passbolt

Which OpenPGP implementation should I use?

There are several ways you can use OpenPGP. The most popular option is to use GnuPG (directly or via GPGME) or another implementation in your favorite language.

There are various language libraries available such as:

• OpenPGP.js: JavaScript alone (used by passbolt extension / cli)
• PHP GnuPG: PHP with GnuPG (used by passbolt server)
• OpenPGP.php: PHP alone (used by passbolt server).
• gpgme.js: JavaScript for GPGME
• GPGME Python: Python with GnuPG.
• PGPy: Python alone.

You can find additional libraries on openpgp.org.

Working with OpenPGP Keys

At the time of installation the passbolt server administrator generates an OpenPGP key pair and stores it in the server keyring. Similarly, clients (such as the passbolt browser extension) generate a pair of keys during the setup. At the end of the setup the client stores its secret key locally and send the public key to the server.

When authenticated, it is possible for a user to gather other user’s public keys, in order to share passwords with them. Prior to sending sensitive data, secrets must be encrypted using the recipient’s public key (e.g. another user, for example) and signed using the sender’s public key.

This serves two purposes:

1. Privacy by encrypting the data and
2. Authenticity by confirming the identity of the sender.

Accessing passbolt server public key

The passbolt server public key is required during the “verify” step of the authentication. This step allows the client to verify the server identity, for example to prevent the unlikely scenario where the domain was seized. Your passbolt server broadcasts its public key at /auth/verify.json:

GET /auth/verify.json

{
    "header": {
        "id": "6f416b88-8062-4e94-ab00-259a4cd2e085",
        "status": "success",
        "servertime": 1554898043,
        "action": "748dcd10-7d15-5498-9aa6-d26de348ff02",
        "message": "The operation was successful.",
        "url": "\/auth\/verify.json",
        "code": 200
    },
    "body": {
        "fingerprint": "2FC8945833C51946E937F9FED47B0811573EE67E",
        "keydata": "-----BEGIN PGP PUBLIC KEY BLOCK-----"
    }
}