API-dokumentation
Allmänt
We have a standard REST API for managing secrets. All requests and responses use the JSON format.
You can use the API to handle both encryption and decryption of the secret outside of our service, without needing to load any assets from us. It also allows you to use any kind of delivery method for the public password part (half of the password which is used to derive the encryption key for the secret from) and basically create any kind of custom configuration for viewing the secret.
Code examples
Please see our API examples on how to use the API.
Authentication
We use two kinds of API keys for authentication:
- Public API keys
- Private API keys
Public API keys are meant for creating a custom self-hosted view secret page. All other API actions require a private API key.
Public API keys can be used in public scripts. Private API keys must always be kept private.
Both API keys contain the type of the key in the key itself so they can be easily distinguished.
The API key must be sent in the Authorization: ApiKey <key> header, like:
Authorization: ApiKey public_key_abc...
Errors
In case of unsuccessful query, the response will have an error object.
The object contains the following fields:
- message: the full error message, e.g. "Ciphertext can\'t be blank"
- field: the field the error is about, e.g. "ciphertext"
The HTTP response status code will also indicate an error, for example:
- 403 Forbidden: the request was not allowed, for example because of invalid API key
- 404 Not Found: the requested secret was not found
View Secret
Request type: GET
Request path: https://password.link/api/secrets/<id>
Status code of successful query: 200 OK
Fetch the ciphertext, private password part and other details of a secret. Requires the public API key.
This API query can be used to create a custom self-hosted view secret page which does not load any scripts or other assets from our service.
Successfully fetching a secret automatically marks it as viewed and so deletes the ciphertext and private password part from our database, making it impossible to view the secret again.
Required parameters- id: the id of the secret, for example dT5g
Exempel på fråga
curl -H "Authorization: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g
Exempel på svar
{
"data": {
"id": "iD för den hemliga informationen",
"ciphertext": "the ciphertext of the secret",
"password_part_private": "the private password part of the secret",
"message": "the message for the secret, if set"
},
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Code example
Please see our API examples.
Create Secret
Request type: POST
Request path: https://password.link/api/secrets
Status code of successful query: 201 Created
This API call also supports adding an attachment to the secret. Please contact us for more details.
Create an encrypted secret.
Encrypting the secret client-side before sending it to our API requires creating an SJCL compatible ciphertext JSON string. Please refer to the <a href=\"https://github.com/bitwiseshiftleft/sjcl\">SJCL documentation</a> for proper format of the JSON string, and see our <a href=\"/p/docs/api/examples\">Exempel på API</a> for examples on how to create the ciphertext.
Creating the password for encrypting the secret
The password which is used to encrypt the secret in AES must consist of two 18 character long strings. The actual encryption key will be the concatenation of these two strings ("private part" + "public part") and is derived from the password by SJCL using PBKDF2.
Example of creating the private and public password parts:
Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Private part: fkgjbnvlakwiejgutn
=> Public part: FIGKEOTIRUBNAKQJRL
The private part needs to be Base64 encoded before sending over to our API. If you use the view secret page provided by us, you must also Base64 encode the public part. If you use a self-hosted view secret page, you can use the same method or create your own. Please see our <a href=\"/p/docs/api/examples\">Exempel på API</a> for reference implementations.
Required SJCL AES settings
You must use the following settings for AES when encrypting the secret:
- Mode: AES-GCM (SJCL setting: "mode:gcm")
- Key size: 256 bits (SJCL setting: "ks:256")
- Key derivation function: PBKDF2 (SJCL default)
- PBKDF2 iterations: 10000 (SJCL setting: "iter:10000")
Request payload
{
"ciphertext": "ciphertext",
"password_part_private": "password_part_private",
"description": "description",
"message": "message",
"expiration": "expiration",
"view_button": "view_button",
"captcha": "captcha",
"password": "password",
"max_views": "max_views"
}
Parametrar för begäran
- ciphertext: An SJCL compatible ciphertext JSON string of the secret, encoded in Base64.
- password_part_private: the private password part which was used to encrypt the secret, in Base64.
- description (optional): a description for the secret. Cannot be seen when viewing the secret.
- message (optional): a message for the secret. Will be shown along the secret.
- expiration (optional): an expiration time for the secret, in hours. Possible values: 0-350.
- view_button (optional): show a view secret button instead of showing the secret immediately after opening the link. To enable this feature set this to true.
- captcha (optional): show a simple CAPTCHA before showing the secret, mainly for blocking automated scanners. To enable this feature set this to true.
- password (optional): a password for the secret.
- max_views (optional): how many times the secret can be viewed. Possible values: 1-100.
Code example
Please see our API examples.
List Secrets
Request type: GET
Request path: https://password.link/api/secrets
Status code of successful query: 200 OK
Fetch a list of secrets. Does not contain the ciphertexts private password parts, only IDs, descriptions and the like.
Limit och offset
The maximum amount of returned secrets for each query is limited to 50. You can control the offset with the optional offset query parameter.
Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secrets?offset=50
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secrets
Exempel på svar
{
"data": [
{
"id": iD för den hemliga informationen,
"created_at": when the secret was created,
"message": the message for the secret,
"description": the description of the secret,
"view_button": is the view secret button enabled,
"captcha": is the CAPTCHA enabled,
"password": does the secret have a password,
"expiration": expiration time in hours,
"expired": has the secret expired,
"view_times": how many times the secret has beew viewed,
"max_views": the maximum amount of times the secret can be viewed,
"views": [
{
"viewed_at": a timestamp of when the secret was viewed,
"viewed_by_ip": IP address of the viewer,
"viewed_by_user_agent": user agent of the viewer
}
]
}
],
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Delete Secret
Request type: DELETE
Request path: https://password.link/api/secrets/<id>
Status code of successful query: 200 OK
Delete a secret.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \\
-X DELETE https://password.link/api/secrets/dT5g
Exempel på svar
{
"data": null,
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Skapa hemlig begäran
Typ av begäran: POST
Sökväg för begäran: https://password.link/api/secret_requests
Statuskod för framgångsrik fråga: 201 Created
Skapa en ny hemlig begäran.
Parametrar för begäran
- description: beskrivning för den hemliga begäran.
- message: meddelande för Secret Request-tittaren.
- expiration: utgångstid för den hemliga begäran, i timmar.
- limit: användningsgräns för den hemliga begäran.
- send_request_to_email: skicka den skapade länken för hemlig begäran till den angivna e-postadressen.
- send_to_email: skicka den hemliga länken som skapats med hjälp av den hemliga begäran till den angivna e-postadressen.
- secret_description: beskrivning för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_message: meddelande för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_expiration: utgångstid i timmar för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_password: lösenord för den hemlighet som skapats med hjälp av hemlighetsbegäran, i timmar.
- secret_max_views: visningsgräns för den hemlighet som skapats med hjälp av hemlighetsbegäran.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \
-H "Content-Type: application/json" -X POST https://password.link/api/secret_requests
Exempel på svar
{
"data": {
"id":"5e976e6e-d205-4f58-8df9-5ac0048bc702"
},
"metadata": {
"secrets_total":70,
"secrets_usage":25,
"secrets_allowance":100,
"secret_requests_total":10,
"secret_requests_allowance":100
}
}
Lista hemliga förfrågningar
Typ av begäran: GET
Sökväg för begäran: https://password.link/api/secret_requests
Statuskod för framgångsrik fråga: 200 OK
Limit och offset
The maximum amount of returned results for each query is limited to 50. You can control the offset with the optional offset query parameter.
Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secret_requests?offset=50
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secret_requests
Exempel på svar
{
"data":[
{
"id":"5e976e6e-d205-4f58-8df9-5ac0048bc702",
"description":"example",
"message":"example",
"expiration":3,
"limit":1,
"send_to_email":"example@example.com",
"secret_description":"example",
"secret_message":"example",
"secret_expiration":"example",
"secret_max_views":4,
"secret_password":false,
"template_id":null
}
],
"metadata": {
"secrets_total":70,
"secrets_usage":25,
"secrets_allowance":100,
"secret_requests_total":10,
"secret_requests_allowance":100
}
}
Begäran om att ta bort hemlighet
Typ av begäran: DELETE
Sökväg för begäran: https://password.link/api/secret_requests/<id>
Statuskod för framgångsrik fråga: 200 OK
Ta bort en hemlig begäran.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \
-X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702
Exempel på svar
{
"data": null,
"metadata": {
"secrets_total":70,
"secrets_usage":25,
"secrets_allowance":100,
"secret_requests_total":10,
"secret_requests_allowance":100}
}