SendSafely REST API

This article outlines the steps required to access the SendSafely REST API and how to create a SendSafely package. The SendSafely REST API is available to users who are on an Enterprise Plan.

Please note that while you can use the SendSafely API to create packages, it's easier to do so using one of our clients for Node.js, Python, .NET, or Java. These clients handle much of the heavy lifting for you, especially around timestamp and signature formatting and trusted browser and master key encryption. We recommend them as better starting points for customers seeking to automate their SendSafely workflows.

Accessing the REST API

The SendSafely REST API Base URL is the following:

https://app.sendsafely.com/api/v2.0

The SendSafely REST API requires the following authentication-related HTTP headers on every request:

• ss-api-key: SendSafely API Key obtained from the API Keys section of the Edit Profile page when logged into SendSafely

• ss-request-timestamp: Generated in your client code using a standard date/time function to generate the current timestamp, and it should be in a format similar to the following:

2019-01-14T22:24:00+0000

• ss-request-signature: HMAC calculated in your client represented by the following pseudo code:

HmacSHA256(API_SECRET, API_KEY + URL_PATH + TIMESTAMP + REQUEST_BODY)

API_SECRET is also obtained from the API Keys section of the Edit Profile page, and is only available when the API_KEY is first generated

API_KEY is the same value passed for the ss-api-key header

URL_PATH is the portion of the path after the Base URL

Example: https://demo.sendsafely.com/api/v2.0/package/

URL_PATH = /api/v2.0/package/

TIMESTAMP is the same value passed for the ss-request-timestamp header

REQUEST_BODY data passed in the body of an HTTP request (typically only relevant for POST, PUT, etc)

Creating a new Package

The following steps can be used to create a new package using SendSafely:

Step 1 - Create a new (empty) Package

https://rest-api-docs.sendsafely.com/#7c29b522-c536-4260-afcb-ed0c4b11a607

Step 2 -  Add a file to the Package

Note: With SendSafely, files are encrypted using a PGP symmetric key (passphrase). The passphrase consists of the Server Secret (obtained from Step 1) combined with a Client Secret (also referred to as a “keycode” in Step 4). The Client Secret is generated client-side and should be a random 256-bit alphanumeric string. You will need this value after you perform Step 4 in order to construct the secure link that you will send to the recipients.

Before encrypting the file, you should also split the file into one or more “parts” to allow for faster processing when the user downloads and saves the file. We recommend using 2.5MB as the file part size. The total number of file parts should be calculated before you perform this step.

a. Generate a new File Id

https://rest-api-docs.sendsafely.com/#47f09dca-9985-4b82-92c3-32452fd2b5cc 

b. Obtain the S3 Upload URLs for each part

https://rest-api-docs.sendsafely.com/#c5dacd05-0778-49e5-be17-03163de2b3b4

NOTE: Up to 25 upload URLS for each file can be obtained at once. You can use the startSegment parameter to tell the server which file part you would like as the starting point for each request. Note that each URL contains a time-stamped authentication token that is only valid for 60 minutes, so in general you should not obtain these URLs until you are ready to use them.  

c. Upload each file part

Uploads are done directly to S3 using PUT requests to the URLS obtained from Step b above. The body of each PUT request should only include the PGP encrypted file part in binary format.

When encrypting each file part, make sure you use the following PGP options:

• Symmetric-Key Algorithm should be 9 (AES-256)
• Compression Algorithm should be 0 (Uncompressed)
• Hash Algorithm should be 8 (SHA-256)
• Passphrase:  Server Secret concatenated with a random 256-bit Client Secret  
• S2k-count: 65535
• Filename: Any non-null value (typically the FileId + PartNumber)
• Mode: b (62)

d. Mark the file upload as complete

https://rest-api-docs.sendsafely.com/#f0bc2a69-1b8a-4043-bc62-cda89170e04c

Step 3 - Add recipients

https://rest-api-docs.sendsafely.com/#4470d459-a1a9-4df2-a83f-fa77801ffe35 

Step 4 - Finalize the Package

For this step, you will need to calculate the “checksum” parameter using the keycode (Client Secret) and the Package Code (obtained from Step 1). The checksum is generated using PBKDF2-HMAC-SHA256 with the keycode as the password, and the Package Code as the salt.

Use the following inputs for your PBKDF2 function

• Hashing Algorithm - SHA-256
• Password  - Use the keycode for this value  
• Salt - Use the Package Code for this value
• Iteration Count - 1024
• Key Length - 32 bytes  

https://rest-api-docs.sendsafely.com/#90798915-7498-4df6-b1ba-684e59c2eb1f 

Step 5 - Send the Package Link to each Recipient

After the package has been finalized, you will need to provide the Package Link to each of your recipients. The package link should be constructed as follows:

https://sendsafely_hostname/receive/?packageCode=unique_package_code#keycode=unique_keycode

The values in RED above should be replaced with the applicable values for your package:

• sendsafely_hostname - The URL that you use to access SendSafely for your company (ie companyname.sendsafely.com) 
• unique_package_code - The Package Code generated in Step 1 above 
• unique_keycode - The keycode (Client Secret) used in Step 2 above

Downloading a Package

The following steps can be used to download the contents of a package from SendSafely. These steps assume that you have the full Package Link (including the keycode parameter) for the package. 

Step 1 - Retrieve Package Information 

The Package Code from the Package Link is required for this step. You must also be using an API Key that is associated with a user who is listed as a recipient for the package, otherwise you will not be allowed to access the package information. 

https://rest-api-docs.sendsafely.com/#401b07bc-1131-4c76-8033-2fb5539ede9e

Step 2 - Download File Parts 

For each file in the "files" array contained in the Package Information response from Step 1, you will need to do the following:

a. Get Download Urls for each File Part 

Each file is split into multiple smaller "parts" for faster processing. The number of "parts" associated with each file is included as a property within the files array from Step 1. Each part has its own URL, which can be obtained from the download-urls endpoint:

https://rest-api-docs.sendsafely.com/#9cad8656-daaa-47e3-af8f-3e37cac3bf12

This endpoint requires you do provide a "checksum" parameter that is calculated using the keycode (Client Secret) and the Package Code, which are both included in the Package Link. The checksum is generated using PBKDF2-HMAC-SHA256 with the keycode as the password, and the Package Code as the salt.

Use the following inputs for your PBKDF2 function:

• Hashing Algorithm - SHA-256
• Password  - Use the keycode for this value  
• Salt - Use the Package Code for this value
• Iteration Count - 1024
• Key Length - 32 bytes  

NOTE: Up to 25 download URLS for each file can be obtained at once. You can use the startSegment parameter to tell the server which file part you would like as the starting point for each request. Note that each URL contains a time-stamped authentication token that is only valid for 60 minutes, so in general you should not obtain these URLs until you are ready to use them.  

b. Download and Decrypt File Parts 

Each file part will need to be individually downloaded and decrypted using PGP. You will need to use the "Server Secret" (included in the Package Information response from Step 1) and the keycode (Client Secret) in order to compute the required decryption key. 

When decrypting each file part, make sure you use the following PGP options:

• Symmetric-Key Algorithm should be 9 (AES-256)
• Compression Algorithm should be 0 (Uncompressed)
• Hash Algorithm should be 8 (SHA-256)
• Passphrase:  Server Secret concatenated with a random 256-bit Client Secret  
• S2k-count: 65535
• Mode: b (62)

c. Re-assemble Decrypted File Parts 

The decrypted file parts should be re-assembled in order (sequentially based on the file part number) to construct the decrypted file. Within your code you can choose to do this in real-time as each file part is decrypted or at the end once all of your file parts are decrypted. 

For additional information about the SendSafely API, including our Java, C#, JavaScript, and Python SDKs, check out the SendSafely Developer Center.