Getting Started
We recommend downloading the Swagger docs directly from our sandbox environment for the latest, most concise documentation.
Public and private API keys
Caplinked will send you an email with your API public and private keys upon account approval. The private (secret) will be used to sign your API requests to the Caplinked API and should be kept privately (i.e. not committed to your source repository). You will be able to reset/roll your private key as needed. The public key will be used to identify your Caplinked API account.
User Tokens
The user token is used to identify the user resource in your organization. All API requests should specificy this header.
Signing your request
You will need to sign your requests with your private key via the HmacSHA256 algorithm. Below is an example done in javascript:
var api_user_token = 'cd3361c8b8c4a914afbf587c701128bf016xxxxx';
var api_secret_key = '7c1c971ad1f1170b6c984023fc22bcaa0dd21e510bf70772e55867235f7xxxxx';
// utc api request expiration for signature + 1800 seconds (30mins)
var api_exp_date = Math.floor(Date.now() / 1000) + 1800;
var payload = api_key + api_user_token + api_exp_date;
var hash = CryptoJS.HmacSHA256(payload, api_secret_key);
var signature = "Method=HMAC-SHA256 Signature=" + hash;
var headers = {
'x-api-key': api_key,
'x-api-user-token': api_user_token,
'x-api-signature': signature,
'x-api-exp-date': api_exp_date,
}
// curl request example
curl https://sandbox.caplinked.com/api/v1/users/me \
-H "x-api-key: f15fbbd103f66b2e472316857cc37f8378axxxxx" \
-H "x-api-user-token: cd3361c8b8c4a914afbf587c701128bf016xxxxx" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=bb472a31cb557208028c1aab0a159d362fc1efebc23623d81bd05f575d3da9b8" \
-H "x-api-exp-date: 1487628036" \
-X GET
Example
Once you’ve received your CapLinked API key, you can upload and view a file in less than 2 minutes. Follow these commands to get started:
Create your first team
Teams are a way to group users and workspaces.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"team": {"name": "New Team" }}' \
-X POST
Create your first workspace
Workspaces are where files are stored, users are granted access, and activity it recorded.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"workspace": { "name": "New Workspace"}, "team_id": 1 }' \
-X POST
Create a folder
Folders store other folders and files.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"name": "New Folder", "workspace_id":1 }' \
-X POST
Upload a file
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"workspace_id":1, "folder_id":1, "file_name": "NEW_FILE" }' \
--data-binary "@NEW_FILE" \
-X PUT
Get file information
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-X GET
Next Steps
There’s so much more you can do with the CapLinked API. Visit the full documentation for an exhaustive list. Here are just a few examples:
Create a group
Groups are where users gain access to folder and files inside a workspace.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group": {"name": "New Group", "workspace_id":1, "file_managing_abilities": true }}' \
-X POST
Configure permissions for your group
The permissions endpoint are where you decide which files a group can access, and what types of access they have.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group_id": 1, "workspace_id": 1, "verb": "set", "folder_action": "download"}' \
-X PUT
Enable watermarking for your group
Custom watermarks are applied to documents in the viewer and upon download. Dynamic watermarks may include crucial user information, such as name, time stamps, email, and IP address.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group": {"watermarking": true }}' \
-X PUT
Create a non-admin user
This user represents the person viewing documents. You will receive a token to make requests on their behalf. Store this user_token so all requests made with it are tied to that user.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"user": {"email": "email@example.com", "first_name": "user_first_name", "last_name": "user_last_name", "time_zone": "UTC" }}' \
-X POST
Add user to the group
Give permission to a user for viewing folders and files. Use the group id created before in the url.
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-X POST
Note: Use the non-admin user token to request downloads or view files with watermarking enabled.