5-minute quick start

This guide takes you from nothing to a vault you created through the API. It uses curl, so there is nothing to install. The official SDKs are not published yet.

1. Check you can reach the API

curl -i https://api.essence.digital/api/v1/vaults

You get 401 Unauthorized with a WWW-Authenticate: Bearer header. That is the answer you want: the request reached the vault service's route, and the route refused it because it carried no credentials. A path that does not exist answers 404 instead, so a 401 here means the address is right.

2. Get an access token

Every request to api.essence.digital is authenticated with a Bearer access token. See Authentication for how tokens are issued, how long they last and how to refresh them. Keep the token in an environment variable, never in source code:

export ESSENCE_ACCESS_TOKEN='<your access token>'

API keys

The public edge does not yet accept API keys on their own. A request that sends only an X-Api-Key header gets the same 401 as a request with no credentials. Use a Bearer token.

3. List your vaults

curl -s "https://api.essence.digital/api/v1/vaults?pageNumber=1&pageSize=10" \
  -H "Authorization: Bearer $ESSENCE_ACCESS_TOKEN"

A 200 means your token works. The body is one page of the vaults you own: items holds the vaults, possibly none, and totalCount says how many there are in all.

4. Create a vault

Essence never receives your users' plaintext or their keys. A vault is created with the metadata of the encryption your application has already performed on the device: which key it used, and the AES-256-GCM initialisation vector, salt and authentication tag, each base64-encoded.

curl -s -X POST https://api.essence.digital/api/v1/vaults \
  -H "Authorization: Bearer $ESSENCE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first vault",
    "keyId": "<the id of the key your app encrypted with>",
    "initializationVector": "<base64>",
    "salt": "<base64>",
    "authenticationTag": "<base64>"
  }'

A 201 Created returns the new vault. If a field is missing or is not valid base64, you get a 400 problem document whose validationErrors names each field that failed. name may contain letters, numbers, spaces, hyphens and underscores, up to 200 characters.

Next

• Your first API call: what each header in those responses tells you
• API overview