API documentation

Getting Started

This quickstart will take you through the basics of the Deftlr model and the usage of the Deftlr API.

Authentication and Encryption Model

Your app using the API will access Deftlr. To do this, you will need to authenticate with Deftlr to verify your identity and grant your app permission to access the stored content.

Deftlr uses a custom header for the purpose of authentication and authorization. Every API request should contain a header named ClientVerificationToken holding the Deftlr API access key.

ClientVerificationToken=...access key...

Every item stored in Deftlr has six important properties:

  • id: unique item id
  • SID: secure id
  • Tag: unique tag used for storing and searching the item
  • IV: encryption initialization vector
  • SALT: encryption salt value
  • Content: encrypted content

The id is known only to the creator of the item and to the person that knows the token used for the content encryption resp. decryption (use api/id to generate new ids). The SID is the item id encrypted with the same IV and SALT values, used for the encryption of the content. The tag is the unique name of the vault holding an item.

The encryption algorithm used by the Deftlr web client is AES with CBC mode and PKCS7 padding. The secret is derived with a PBKDF2 function with 1000 iterations. (current JavaScript implementation). The Deftlr web client encryption library is CryptoJS.

Summary

The API methods can be placed in two categories - methods working with tag (search / master) and methods working with id (read / create / delete). This was done to reduce the download size and increase the security. Viewing / Deleting an item is actually a three step operation: search by tag, decrypt sid to retrieve id, read/delete by id. You do not need to download the complete item if the user can not decrypt the id. This leads to easier and cleaner application implementation. All encryption resp. decryption operations use the same secret (the token), IV and SALT values.

Our JavaScript API wrapper library can be found here: JavaScript DeftlrCryptoLibrary.

We are currently working to release a .NET and Java API wrapper libraries.

We offer a Swagger API definition: https://deftlr.com/apidefinitions.json

Using the Deftlr API

Search item by tag:

curl -H "ClientVerificationToken:[API access token]" https://deftlr.com/api/search/hello

Search items by master tag:

curl -H "ClientVerificationToken:[API access token]" https://deftlr.com/api/master/august2017

Search items by default API key master tag:

curl -H "ClientVerificationToken:[API access token]" https://deftlr.com/api/master

Read item by id:

curl -H "ClientVerificationToken:[API access token]" https://deftlr.com/api/read/[id]

Create(store) new item:

curl -H "ClientVerificationToken:[API access token]" -H "content-type:application/json" -X POST -d "{'Id':'id','Tag':'customtag','Salt':'...','IV':'...','Content':'...','SID':'...'}" https://deftlr.com/api/create

Delete item by id:

curl -H "ClientVerificationToken:[API access token]" -X DELETE https://deftlr.com/api/delete/[id]

Generate new id:

curl -H "ClientVerificationToken:[API access token]" https://deftlr.com/api/id

Deftlr API

[ Scheme and Base url: https://deftlr.com ]

Create

POST/api/create
Creates a new item. The item can be accessed from the deftlr.com website or the API. Some options (for example the expiration time) will be set automatically regarding the API token rights. If an option is set for which you do not have the rights, then this option is ignored resp. the default value is set. Example1: Alice does not have the rights to create an undeletable item. The create post payload contains the field IsNotDeletable = true. The new item is created and the IsNotDeletable flag is set to false. Example2: Bob does not have the rights to set custom master tags (in order to create sub collections). The create post payload contains the field Master = "bob1". The new item is created with the API key default master tag.

Parameters

NameDescription
serviceItem *
(body)
{
	"id": "d369ddb2-f608-4af7-a431-720ff3b4bff6",
	"Tag": "secretmessage1",
	"IV": "string",
	"Salt": "string",
	"SID": "string",
	"Content": "string",
	"MasterTag": "department1",
	"IsNotDeletable": true,
	"FileName": "document.txt",
	"FileMimeType": "text/plain"
}

Responses

CodeDescription
200

OK

Delete

DELETE/api/Delete/{id}
Deletes the item with the specified id unless the IsNotDeletable flag is true.

Parameters

NameDescription
id *
string
(path)

Responses

CodeDescription
200

OK

Id

GET/api/Id
Generates a system wide unique id, needed for new items.

Parameters

No parameters

Responses

CodeDescription
200

OK

Master

GET/api/Master/{masterTag}
Retrieves a list of items for the specified master tag. If the parameter is empty, then the default API master tag is used.

Parameters

NameDescription
masterTag
string
(query)

Responses

CodeDescription
200

OK

[
	{
		"Tag": "string",
		"CreationDate": "2017-07-11T20:29:51.429Z",
		"FileMimeType": "string"
	}
]

Read

GET/api/Read/{id}
Retrieves the item (including content) with the specified id.

Parameters

NameDescription
id *
string
(path)

Responses

CodeDescription
200

OK

{
	"Content": "string",
	"CreationDate": "2017-07-11T20:29:51.431Z",
	"Expires": true,
	"ExpirationDate": "2017-07-11T20:29:51.431Z",
	"IV": "string",
	"Salt": "string",
	"FileName": "string",
	"FileMimeType": "string"
}

Search

GET/api/Search/{tag}
Search for an item with the specified tag. If nothing is found, then the response property IsEmpty is set to true.

Parameters

NameDescription
tag *
string
(path)

Responses

CodeDescription
200

OK

{
	"SID": "string",
	"IV": "string",
	"Salt": "string",
	"IsEmpty": true
}

Models

ServiceItem {
id: string
example: d369ddb2-f608-4af7-a431-720ff3b4bff6

Unique id generated by an api/id call

Tag: string
example: secretmessage1

Unique tag

IV: string

Encryption initialization vector

Salt: string

Encryption salt

SID: string

Encrypted id using current IV and salt

Content: string

Encrypted content using current IV and salt

MasterTag: string
example: department1

Unique master tag to allow the creation of tag collections

IsNotDeletable: boolean

If true the item could not be deleted manually

FileName: string
example: document.txt

Filename in case the encrypted content is a file

FileMimeType: string
example: text/plain

File MIME type in case the encrypted content is a file

}
#/definitions/SearchByMasterTagResponseSearchByMasterTagResponse {
Tag: string

Unique item tag

CreationDate:string
FileMimeType: string

File MIME type in case the item is storing a file

}
#/definitions/ReadResponseReadResponse{
Content:string
CreationDate:string
Expires:boolean
ExpirationDate:string
IV:string
Salt:string
FileName:string
FileMimeType:string
}
#/definitions/SearchResponseSearchResponse {
SID: string

Encrypted id using current IV and salt

IV: string

Encryption initialization vector

Salt: string

Encryption salt

IsEmpty: boolean
readOnly: true

True if the specified tag was not found

}