Help Search

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 (hence referred to as “APIs”) 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

Passbolt API return 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.

So for example requesting a single resource by id will result in something like: ``

Notice: The title under header in deprecated and will be removed in future release. Similarly the code is only indicated to ease readibility for administrator when debugging and should not be relied on.

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,
        "title": "app_resources_add_error",
        "action": "ad8bbc35-6435-538e-b1a7-80b87bcedb6a",
        "message": "Could not validate resource data.",
        "url": "\/resources.json?api-version=v2",
        "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 (“A name is required”) the actual error message.

API Versions

Passbolt API is versioned. Historically passbolt supports two different formats for interacting with the API. At the moment the server component currently supports format version 2 and 1, where v1 is the default (even for v2 server component) for backward compatibility reasons. However this behavior will change in the future so please use (or switch) to API version 2 as soon as possible to minimize refactoring in your application down the road.

You can target a specific API version by including a query string api-version in your requests. For example to get a list of all resources using version 1, you can do

GET /resources.json?api-version=v1
{
    "header": {
        "id": "b8ab8696-e5a1-4a06-bfbc-a7b77efd8f10",
        "status": "success",
        "servertime": 1554897334,
        "title": "app_resources_index_success",
        "action": "c506210f-7866-5691-8fc1-58772e8f49f1",
        "message": "The operation was successful.",
        "url": "\/resources.json?api-version=v1",
        "code": 200
    },
    "body": [
        {
            "Resource": {
                "id": "8e3874ae-4b40-590b-968a-418f704b9d9a",
                "name": "apache",
                "username": "www-data",
                "uri": "http:\/\/www.apache.org\/",
                "description": "Apache is the world\u0027s most used web server software.",
                "deleted": false,
                "created": "2019-04-02 12:05:58",
                "modified": "2019-04-03 12:05:58",
                "created_by": "f848277c-5398-58f8-a82a-72397af2d450",
                "modified_by": "f848277c-5398-58f8-a82a-72397af2d450"
            }
        },
        {
            "Resource": {
                "id": "09c790c0-c003-53c8-a640-25d33cfebc22",
                "name": "bower",
                "username": "bower",
                "uri": "bower.io",
                "description": "A package manager for the web!",
                "deleted": false,
                "created": "2017-04-04 12:05:58",
                "modified": "2018-04-04 12:05:58",
                "created_by": "640ebc06-5ec1-5322-a1ae-6120ed2f3a74",
                "modified_by": "640ebc06-5ec1-5322-a1ae-6120ed2f3a74"
            }
        }
    ]
}

Notice how the associated objects like “Modifier”, “Creator” and “Tag” are on the same level as “Resource”.

Whereas the same request using v2 option will be structured differently:

GET /resources.json?api-version=v2
{
    "header": {
        "id": "58e1d35d-d6cb-4cb7-94b9-f43bae176bfa",
        "status": "success",
        "servertime": 1554897573,
        "title": "app_resources_index_success",
        "action": "c506210f-7866-5691-8fc1-58772e8f49f1",
        "message": "The operation was successful.",
        "url": "\/resources.json?api-version=v2",
        "code": 200
    },
    "body": [
        {
            "id": "8e3874ae-4b40-590b-968a-418f704b9d9a",
            "name": "apache",
            "username": "www-data",
            "uri": "http:\/\/www.apache.org\/",
            "description": "Apache is the world\u0027s most used web server software.",
            "deleted": false,
            "created": "2019-04-02T12:05:58+00:00",
            "modified": "2019-04-03T12:05:58+00:00",
            "created_by": "f848277c-5398-58f8-a82a-72397af2d450",
            "modified_by": "f848277c-5398-58f8-a82a-72397af2d450"
        },
        {
            "id": "09c790c0-c003-53c8-a640-25d33cfebc22",
            "name": "bower",
            "username": "bower",
            "uri": "bower.io",
            "description": "A package manager for the web!",
            "deleted": false,
            "created": "2017-04-04T12:05:58+00:00",
            "modified": "2018-04-04T12:05:58+00:00",
            "created_by": "640ebc06-5ec1-5322-a1ae-6120ed2f3a74",
            "modified_by": "640ebc06-5ec1-5322-a1ae-6120ed2f3a74"
        }
    ]
}

This time the associated fields like “modifier”, “creator” and “tags” are all part of the single “Resource” object they belong to and the object type is not specified anymore. This is just one of the major changes over v1. 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. The solution uses end-to-end encryption, 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 assume you are familiar with these concepts.

password exchange using passbolt fig. password exchange using passbolt

Which OpenPGP implementation should I use?

There are several way 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:

You can find the whole list 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 users public keys, in order to share passwords with them. Prior to sending sensitive data, secrets must be encrypted using the recipient (e.g. another user for example) public key and signed using sender’s.

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

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?api-version=v2",
        "code": 200
    },
    "body": {
        "fingerprint": "2FC8945833C51946E937F9FED47B0811573EE67E",
        "keydata": "-----BEGIN PGP PUBLIC KEY BLOCK-----"
    }
}

Last updated

This article was last updated on April 23rd, 2019.

If you are familiar with the high level API concepts and only looking for the endpoint implementation details, there is a repository with the latest OpenAPI 2.0 specifications (compatible with Swagger).

OpenAPI Specs