Help Search

Edit on github

Secret

Secret endpoints are used to manage secrets on a Resource.

The Secret object

Attribute Type Description Format
id String Unique ID of the secret object in UUID format. UUID
user_id String The target user id in UUID format.
This is the user whose public key was used to encrypt the plaintext password. 		UUID
resource_id String The target resource id in UUID format. UUID
data String PGP encrypted plaintext password. ASCII Armored binary to textual format.
created String Datetime when the resource was created ISO 8601 Datetime format
2014-02-01T09:28:56.321-10:00
modified String Datetime when the resource was last modified ISO 8601 Datetime format
2014-02-01T09:28:56.321-10:00

View a resource’s secret

To get a resource’s secret you can make the following request:

GET /secrets/resource/<resourceId>.json

Possible responses

Code Description
200 OK
Response includes the Secret object.
400 Bad Request
The resource id is not valid.
403 Authentication Failure
The user making the request is not authenticated.
404 Not Found
The secret does not exist.

Example Request

So a request to get secret for a resource identified by 8e3874ae-4b40-590b-968a-418f704b9d9a will look like

https://www.passbolt.test/secrets/resource/8e3874ae-4b40-590b-968a-418f704b9d9a.json

Upon success this will return a payload like this

{
    "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",
        "data": "-----BEGIN PGP MESSAGE-----",
        "created": "2019-04-04T12:06:50+00:00",
        "modified": "2019-04-04T12:06:50+00:00"
    }
}

Retrieving the plaintext password

Please note that the returned secret is encrypted using the public key of the user making the request. To retrieve the plaintext password, you must decrypt it using the associated secret key.

The plaintext password is encrypted using the user’s public key it’s shared with. So to decrypt it, you must have secret/private key of that user in your keyring.

In the example above, the string under the key data is the encrypted plaintext password. To decrypt it to retrieve the plaintext password, you can use gpg -d or gpg --decrypt command. Here is an example

$ echo "<encrypted_token_from_server>" | gpg -d

It should output the plaintext password on the console.

$ echo "<encrypted_token_from_server>" | gpg -d
gpg: encrypted with 4096-bit RSA key, ID 7A8E6D66F5DC4C49, created 2019-03-13
      "Abhinav Kumar <[email protected]>"
hello

In the example above “hello” is the plaintext password.

Last updated

This article was last updated on May 20th, 2019.

For another perspective on the API you browse the OpenAPI 2.0 specifications using the dedicated API reference site (Swagger UI).

API Reference

You can also find the latest OpenAPI 2.0 specifications directly on the dedicated repository.

OpenAPI Specs repository