Working with Secrets

This guide assumes you have obtained an access token to authorize your API requests.

Each secret consists of its name and its value. Once created, the secret is identified in API calls by its name. As you change the value of a secret, the old values are not overwritten. Rather, new versions of the secret are created.

Note

Sharing a secret changes the API endpoints used to accomplish key tasks. This article describes the API endpoints used to work with secrets that have not been shared. For an overview of the endpoints used to work with shared secrets, see Working with Shared Secrets.

Creating Secrets

Secrets management begins by storing the name and value of a new secret in CryptoMove. When creating a new secret, you can provide a classification, description and other metadata for the secret. If you do not specify metadata values, default values will be assigned to your new secret. Each secret has the following metadata:

Metadata Name

Default Value

application_type

container

classification

top

cloud_type

aws

description

n/a

enviroment_type

dev

expiration_time

You can also attach custom metadata to the new secret by specifying unique name/value pairs to the JSON request body.

By default, the secret expires after 10 days. You can specify a different value with the expiration_time metadata value, which is an integer representing the number of days until the secret expires. To extend the expiration time later, simply update the metadata of the secret.

For example, to store your database password in CryptoMove, you could make the following request:

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/protect \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]",
  "key_name":"database_password",
  "key_value":"very_secret",
  "metadata":{
    "application_type":"container",
    "classification":"top_secret",
    "cloud_type":"aws",
    "description":"the database password we use",
    "environment_type":"dev",
    "expiration_time":3,
    "customOne":"custom_metadata"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/protect',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'your_authentication_token' },
  body: '{"email":"[email protected]","key_name":"database_password","key_value":"very_secret","classification":"top_secret","description":"the database password we use","expiration_time":3,"customOne":"custom_metadata"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.cryptomove.com/v1/user/secret/protect")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["authorization"] = 'your_authentication_token'
request["content-type"] = 'application/json'
request.body = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"very_secret\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3,\"customOne\":\"custom_metadata\"}"

response = http.request(request)
puts response.read_body

var data = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"very_secret\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3,\"customOne\":\"custom_metadata\"}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/protect");
xhr.setRequestHeader("authorization", "your_authentication_token");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/protect"

payload = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"very_secret\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3,\"customOne\":\"custom_metadata\"}"
headers = {
    'authorization': "your_authentication_token",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Automatically Deleting Secrets

When creating a secret, you can use the delete_time parameter to set a time when the secret will be automatically removed from CryptoMove. This parameter is different than the expiration_time metadata value; a secret is not deleted when a secret expires. The default value of delete_time is 525600000 (1000 years), so you don't need to worry about a secret being unintentionally removed from CryptoMove. However, if you want to automatically remove a secret MySecret01 from CryptoMove in 30 days (43,200 minutes), you could pass the following JSON request body to the /protect endpoint:

JSON

{
  "email":"[email protected]",
  "key_name":"MySecret01",
  "key_value":"very_secret",
  "delete_time":"43200"
}

Listing Your Secrets

To list all of your secrets invoke the following API request. This endpoint does not return the values of secrets. You can obtain the value of a secret stored in CryptoMove by using the expose endpoints described below.

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/list_no_dup \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/list_no_dup',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'your_authentication_token',
     accept: 'application/json' },
  body: '{"email":"[email protected]"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/list_no_dup',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'your_authentication_token',
     accept: 'application/json' },
  body: '{"email":"[email protected]"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

var data = "{\"email\":\"[email protected]\"}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/list_no_dup");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("authorization", "your_authentication_token");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/list_no_dup"

payload = "{\"email\":\"[email protected]\"}"
headers = {
    'accept': "application/json",
    'authorization': "your_authentication_token",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

If you want to list information about all versions of a specific secret, use the /user/secret/version_list endpoint.

Revealing Secrets

The value of a secret is safe in the CryptoMove key vault until its value is needed by an application. When using the API, the only way to obtain the value of your secret is by using the expose endpoints. Listing secrets provides information about the secret, including its name, but does not reveal the value of a secret.

For example, to retrieve the database password you stored earlier, invoke the following:

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/expose \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]",
  "key_name":"database_password"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/expose',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'your_authentication_token' },
  body: '{"email":"[email protected]","key_name":"database_password"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.cryptomove.com/v1/user/secret/expose")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["authorization"] = 'your_authentication_token'
request["content-type"] = 'application/json'
request.body = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\"}"

response = http.request(request)
puts response.read_body

var data = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\"}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/expose");
xhr.setRequestHeader("authorization", "your_authentication_token");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/expose"

payload = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\"}"
headers = {
    'authorization': "your_authentication_token",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

If you want to reveal the value of an older version of a secret, use the /user/secret/version_expose endpoint.

If you want to reveal the value of a shared secret, see Revealing Shared Secrets.

Updating Secrets

To update the value of an existing secret, simply call the protect endpoint again, passing the same secret name along with the new value. CryptoMove will not override your current secret's value; instead, a new version of that secret is created.

For example, if you changed your database password from very_secret to new_very_secret_password and want to save that new password in CryptoMove, invoke the following:

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/protect \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]",
  "key_name":"database_password",
  "key_value":"new_very_secret_password"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/protect',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'your_authentication_token' },
  body: '{"email":"[email protected]","key_name":"database_password","key_value":"new_very_secret_password","classification":"top_secret","description":"the database password we use","expiration_time":3}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.cryptomove.com/v1/user/secret/protect")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["authorization"] = 'your_authentication_token'
request["content-type"] = 'application/json'
request.body = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"new_very_secret_password\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3}"

response = http.request(request)
puts response.read_body

var data = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"new_very_secret_password\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/protect");
xhr.setRequestHeader("authorization", "your_authentication_token");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/protect"

payload = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_value\":\"very_secret\",\"classification\":\"top_secret\",\"description\":\"the database password we use\",\"expiration_time\":3}"
headers = {
    'authorization': "your_authentication_token",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

If you want to update the value of a shared secret, see Updating Shared Secrets

Sharing Secrets

You can share your secrets stored in the CryptoMove key vault with other CryptoMove users. To learn more, see Sharing Secrets.

Updating a Secret's Metadata

Aside from updating the value, a user with write access to a secret or shared secret can update the description, classification and other metadata of the secret. CryptoMove provides some standard metadata, but you can add custom name/value pairs to the JSON request body to define additional metadata for the secret. Only specify name/value pairs for the metadata that you want to change; the other existing metadata will be not be affected.

For example, the following request changes the classification and expiration of the database_password secret. Use the list_no_dup endpoint to find out the latest version of the secret.

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/update_key_metadata \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]",
           "key_name":"database_password",
           "key_version":3,
           "metadata":{"classification":"sensitive","expiration_time":8}}'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/update_key_metadata',
  headers: {authorization: 'eyJhbGciOAccessToken', 'content-type': 'application/json'},
  body: '{"email":"[email protected]","key_name":"database_password","key_version":3,"metadata":{"classification":"sensitive","expiration_time":8}}'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.cryptomove.com/v1/user/secret/update_key_metadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'eyJhbGciOAccessToken'
request["content-type"] = 'application/json'
request.body = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_version\":3,\"metadata\":{\"classification\":\"sensitive\",\"expiration_time\":8}}"

response = http.request(request)
puts response.read_body

var data = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_version\":3,\"metadata\":{\"classification\":\"sensitive\",\"expiration_time\":8}}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/update_key_metadata");
xhr.setRequestHeader("authorization", "eyJhbGciOAccessToken");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/update_key_metadata"

payload = "{\"email\":\"[email protected]\",\"key_name\":\"database_password\",\"key_version\":3,\"metadata\":{\"classification\":\"sensitive\",\"expiration_time\":8}}"
headers = {
    'authorization': "eyJhbGciOAccessToken",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Deleting Secrets

When you no longer need a secret, it can be removed from the CryptoMove key vault. Only the user who created a secret can delete it.

For instance, if you want to remove two secrets, MySecret01 and MySecret02, from CryptoMove, you can invoke the following.

curl --request POST \
  --url https://api.cryptomove.com/v1/user/secret/delete \
  --header 'authorization: eyJhbGciOAccessToken' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]",
           "key_name":["MySecret01","MySecret02"]}'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.cryptomove.com/v1/user/secret/delete',
  headers: {authorization: 'eyJhbGciOAccessToken', 'content-type': 'application/json'},
  body: '{"email":"[email protected]","key_name":["MySecret01","MySecret02"]}'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.cryptomove.com/v1/user/secret/delete")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'eyJhbGciOAccessToken'
request["content-type"] = 'application/json'
request.body = "{\"email\":\"[email protected]\",\"key_name\":[\"MySecret01\",\"MySecret02\"]}"

response = http.request(request)
puts response.read_body

var data = "{\"email\":\"[email protected]\",\"key_name\":[\"MySecret01\",\"MySecret02\"]}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.cryptomove.com/v1/user/secret/delete");
xhr.setRequestHeader("authorization", "eyJhbGciOAccessToken");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

import requests

url = "https://api.cryptomove.com/v1/user/secret/delete"

payload = "{\"email\":\"[email protected]\",\"key_name\":[\"MySecret01\",\"MySecret02\"]}"
headers = {
    'authorization': "eyJhbGciOAccessToken",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

You can also delete a specific version of a secret with the version_delete endpoint.

When creating a secret, you can specify a time when you want the secret to be automatically removed from CryptoMove. For more information, see Automatically Deleting Secrets.

Updated 4 months ago

What's Next

Sharing Secrets

CryptoMove

The CryptoMove Developer Hub

Search results for "{{ search.query }}"

Working with Secrets

Note

Creating Secrets

Automatically Deleting Secrets

Listing Your Secrets

Revealing Secrets

Updating Secrets

Sharing Secrets

Updating a Secret's Metadata

Deleting Secrets

What's Next

Working with Secrets

Suggested Edits are limited on API Reference Pages