NAV Navbar
http java shell

Introduction

Welcome to the Karmahostage EAAS API!

You can use our API to access Karmahostage API endpoints, which allows you to perform cryptographic algorithms on data using your keys, securely stored on Karmahostage.

At this point, we don't have any libraries yet, but we're working on it! f

Authentication

To authorize, use this code:

GET http://api.karmahostage.com/keys
X-API-KEY: sk_XXX
Karmahostage karmahostage = 
    Karmahostage.builder()
                .apikey("sk_...")
                .build();
curl "https://api.karmahostage.com"
  -H "X-API-KEY: sk_xxx"

Make sure to replace sk_xxx with the api key that you generated using https://dashboard.karmahostage.com

Karmahostage uses API keys to allow access to the API. You can register a application API key at our developer portal.

Karmahostage expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API: sk_xxx

Keys

Create a Cryptographic key

POST https://api.karmahostage.com/keys
X-API-KEY: "sk_xxx"

{
    "name": "name_of_the_key",
    "keyType": "AES128_GCM96"
}
curl "http://api.karmahostage.com/keys"
  -H "X-API-KEY: sk_xxx"
  -x POST
  -d "{ "name": "name_of_the_key", "keyType": "AES128_GCM96"}"

The above command returns JSON structured like this:

  {
    "id": "e4dea538-37d3-40df-99a7-da9992d3300c"
  } 

Get All Cryptographic keys

GET https://api.karmahostage.com/keys
X-API-KEY: "sk_xxx"
karmahostage.keys()
            .list()
curl "http://api.karmahostage.com/keys"
  -H "X-API-KEY: sk_xxx"

The above command returns JSON structured like this:

[
  {
    "id": "e4dea538-37d3-40df-99a7-da9992d3300c",
    "name": "My Secret Cryptographic Key",
    "description": "My key that I'll use for secret things",
    "creationDate": "2020-02-18 20:21",
    "latestVersion": 2,
    "minimumDecryptionVersion": 1,
    "minimumEncryptionVersion": 2,  
    "type": "AES_GCM",
    "exportable": false,
    "deletable": false,
    "derived": false
  }
]

This endpoint retrieves all keys linked to your application.

Get a single cryptographic key

GET https://api.karmahostage.com/keys/$key_id
X-API-KEY: "sk_xxx"
karmahostage.keys()
            .retrieve("e4dea538-37d3-40df-99a7-da9992d3300c")
curl "http://api.karmahostage.com/keys/$key_id"
  -H "X-API-KEY: sk_xxx"

This returns a json of the following format:

  {
    "id": "e4dea538-37d3-40df-99a7-da9992d3300c",
    "name": "My Secret Cryptographic Key",
    "description": "My key that I'll use for secret things",
    "creationDate": "2020-02-18 20:21",
    "latestVersion": 2,
    "minimumDecryptionVersion": 1,
    "minimumEncryptionVersion": 2,  
    "type": "AES_GCM",
    "exportable": false,
    "deletable": false,
    "derived": false
  }

Rotate a key

POST https://api.karmahostage.com/keys/e4dea538-37d3-40df-99a7-da9992d3300c/rotate
X-API-KEY: "sk_xxx"
   //TODO: Not Implemented Yet
curl "http://api.karmahostage.com/keys/e4dea538-37d3-40df-99a7-da9992d3300c/rotate"
  -H "X-API-KEY: sk_xxx"
  -H "Content-Type: application/json"
  -x POST

This returns a response with status 200: OK

Keys can be updated by simply using the rotating operation.

This will generate a new encryption key and add it to the keyring for the named key. Future encryptions will use the new key. Old data can still be decrypted, because of the keyring.

Encryption

Encrypt a string using a specific key

POST https://api.karmahostage.com/encrypt
X-API-KEY: "sk_xxx"
Content-Type: application/json

{
  "plainText":"my secret text",
  "keyId":"e4dea538-37d3-40df-99a7-da9992d3300c"
}
karmahostage.keys()
            .retrieve("e4dea538-37d3-40df-99a7-da9992d3300c")
            .encrypt("my secret text")
curl "http://api.karmahostage.com/encrypt"
  -H "X-API-KEY: sk_xxx"
  -H "Content-Type: application/json"
  -x POST
  -d '{"keyId":"e4dea538-37d3-40df-99a7-da9992d3300c", "plainText":"my secret text"}'

The above command returns JSON structured like this:

{
  "cipherText":"vault:v1:VVDSf5jsM1xCtgQEjwq/i5+mIMRxVJe9BVOZCbG2p+U="
}

This endpoint will encrypt a string using the given cryptographic key. All work is done on Karmahostage servers. The key never leaves the servers during the process. Only metadata is fetched over the wire.

Decryption

Decrypt an encrypted String using a specific key

POST https://api.karmahostage.com/decrypt
X-API-KEY: "sk_xxx"
Content-Type: application/json

{
  "cipherText":"vault:v1:VVDSf5jsM1xCtgQEjwq/i5+mIMRxVJe9BVOZCbG2p+U=",
  "keyId":"e4dea538-37d3-40df-99a7-da9992d3300c"
}
karmahostage.keys()
            .retrieve("e4dea538-37d3-40df-99a7-da9992d3300c")
            .decrypt("vault:v1:VVDSf5jsM1xCtgQEjwq/i5+mIMRxVJe9BVOZCbG2p+U=")
curl "http://api.karmahostage.com/decrypt"
  -H "X-API-KEY: sk_xxx"
  -H "Content-Type: application/json"  
  -x POST
  -d '{"keyId":"e4dea538-37d3-40df-99a7-da9992d3300c", "cipherText":"vault:v1:VVDSf5jsM1xCtgQEjwq/i5+mIMRxVJe9BVOZCbG2p+U="}'

The above command returns JSON structured like this:

{
  "plainText":"my secret text"
}

This endpoint will decrypt an encrypted string using the given cryptographic key. All work is done on Karmahostage servers. The key never leaves the servers during the process. Only metadata is fetched over the wire.

Signatures

Sign data with a cryptographic key

POST https://api.karmahostage.com/sign
X-API-KEY: "sk_xxx"
Content-Type: application/json

{
  "plainText":"this is a test",
  "keyId":"e4dea538-37d3-40df-99a7-da9992d3300c"
}
karmahostage.keys()
            .retrieve("e4dea538-37d3-40df-99a7-da9992d3300c")
            .sign("this is a test")
curl "http://api.karmahostage.com/sign"
  -H "X-API-KEY: sk_xxx"
  -H "Content-Type: application/json"  
  -x POST
  -d '{"keyId":"e4dea538-37d3-40df-99a7-da9992d3300c", "plainText":"this is a test"}'

The above command returns JSON structured like this:

{
  "signature": "vault:v1:kNIPpLY6/GfN09oj39k45PM+i8capcFSqFcM411gZaYLjZ1DgyOReg60s35grYT/Zkl21dwhmya1ZVOcU6Gcim63Yn1nF/znnAhgWEVTEeRfsp9UC6V37hyxjfzqd2jZKPzoKEH9JlDlxM47OlvOjJgZm1jKhFk9wKxZd7T8d0onu/EVU+mrahHOC6ubkRkNo2+oa4yLuUvLeg1HvkTF6QYQYzHVynzVFwzhF60+gb2nQFukyOWOcjzKgNPS8VkXlBws0ZmmUEcQyq/ImV0FLH/8PN2P/zNODvqCzTASCgkfE14n+DX2j0Nf4zceyU66fttJNhIxTAA0K5tEgQgWvOxJYyreKCiNY4SeXZ3GScYPrs3hC8v5zUhbImbpB8ZLDvk1aFeELwnOqs6THfjYmUXbGGZMK7rA2rZvZUwvd/9p79IYXev6I/XV+JpPMfVG26bJo+gHzVSLMbFTX7/Lvyie4ePEdS69FzhAspuJZXCZjVmzIDW1TK99EJde45Yg0vziae8RRn4bdkvdJYvBq0MxrrV3RuAgedTTkG4vJnzcVFQKpj8uMO2Q3QhJrG1Hh0/qxHAD0WRcuTLmkFYQ+rAPSKDbqfpv4/Jt1u18jc0r4uv9Vab71Epjt+UYRFVx38/0cnp1gj9fWUqnvGugo+iqC0iRC2ErEm5hRxuv/uo="
}

This endpoint will create a digital signature of the plain text using the key you requested.

Signature Verification

Validate a signature with known plaintext

POST https://api.karmahostage.com/public/verify-signature
X-API-KEY: "sk_xxx"
Content-Type: application/json

{
  "plainText":"this is a test",
  "keyId":"e4dea538-37d3-40df-99a7-da9992d3300c",
  "signature": "vault:v1:kNIPpLY6/GfN09oj39k45PM+i8capcFSqFcM411gZaYLjZ1DgyOReg60s35grYT/Zkl21dwhmya1ZVOcU6Gcim63Yn1nF/znnAhgWEVTEeRfsp9UC6V37hyxjfzqd2jZKPzoKEH9JlDlxM47OlvOjJgZm1jKhFk9wKxZd7T8d0onu/EVU+mrahHOC6ubkRkNo2+oa4yLuUvLeg1HvkTF6QYQYzHVynzVFwzhF60+gb2nQFukyOWOcjzKgNPS8VkXlBws0ZmmUEcQyq/ImV0FLH/8PN2P/zNODvqCzTASCgkfE14n+DX2j0Nf4zceyU66fttJNhIxTAA0K5tEgQgWvOxJYyreKCiNY4SeXZ3GScYPrs3hC8v5zUhbImbpB8ZLDvk1aFeELwnOqs6THfjYmUXbGGZMK7rA2rZvZUwvd/9p79IYXev6I/XV+JpPMfVG26bJo+gHzVSLMbFTX7/Lvyie4ePEdS69FzhAspuJZXCZjVmzIDW1TK99EJde45Yg0vziae8RRn4bdkvdJYvBq0MxrrV3RuAgedTTkG4vJnzcVFQKpj8uMO2Q3QhJrG1Hh0/qxHAD0WRcuTLmkFYQ+rAPSKDbqfpv4/Jt1u18jc0r4uv9Vab71Epjt+UYRFVx38/0cnp1gj9fWUqnvGugo+iqC0iRC2ErEm5hRxuv/uo="
}
curl "http://api.karmahostage.com/sign"
  -H "X-API-KEY: sk_xxx"
  -H "Content-Type: application/json"  
  -x POST
  -d '{"keyId":"e4dea538-37d3-40df-99a7-da9992d3300c", "plainText":"this is a test", "signature": "vault:v1:kNIPpLY6/GfN09oj39k45PM+i8capcFSqFcM411gZaYLjZ1DgyOReg60s35grYT/Zkl21dwhmya1ZVOcU6Gcim63Yn1nF/znnAhgWEVTEeRfsp9UC6V37hyxjfzqd2jZKPzoKEH9JlDlxM47OlvOjJgZm1jKhFk9wKxZd7T8d0onu/EVU+mrahHOC6ubkRkNo2+oa4yLuUvLeg1HvkTF6QYQYzHVynzVFwzhF60+gb2nQFukyOWOcjzKgNPS8VkXlBws0ZmmUEcQyq/ImV0FLH/8PN2P/zNODvqCzTASCgkfE14n+DX2j0Nf4zceyU66fttJNhIxTAA0K5tEgQgWvOxJYyreKCiNY4SeXZ3GScYPrs3hC8v5zUhbImbpB8ZLDvk1aFeELwnOqs6THfjYmUXbGGZMK7rA2rZvZUwvd/9p79IYXev6I/XV+JpPMfVG26bJo+gHzVSLMbFTX7/Lvyie4ePEdS69FzhAspuJZXCZjVmzIDW1TK99EJde45Yg0vziae8RRn4bdkvdJYvBq0MxrrV3RuAgedTTkG4vJnzcVFQKpj8uMO2Q3QhJrG1Hh0/qxHAD0WRcuTLmkFYQ+rAPSKDbqfpv4/Jt1u18jc0r4uv9Vab71Epjt+UYRFVx38/0cnp1gj9fWUqnvGugo+iqC0iRC2ErEm5hRxuv/uo="}'

The above command returns JSON structured like this:

{
  "valid": true
}

Secrets

Secrets are cryptographically secure key-value pairs. They're isolated per applications, which means keys are unique per application. Secrets are encrypted at rest, using state-of-the art cryptographic algorithms. Furthermore, they are protected with ACLs, meaning only the API keys that are generated by your application will be able to access the secrets.

Create a secret

POST https://api.karmahostage.com/secrets
X-API-KEY: "sk_xxx"

{
   "key": "/production/application1",
   "value":"secret_code"
}
curl "http://api.karmahostage.com/secrets"
  -H "X-API-KEY: sk_xxx"
  -x POST
  -d '{"key":"/production/application1", "value":"secret_code"}'

The above command returns JSON structured like this:

  {
    "key": "/production/application1
  }

Get Secret by ID

GET https://api.karmahostage.com/secrets/{id}
X-API-KEY: "sk_xxx"
curl "http://api.karmahostage.com/secrets/{id}"
  -H "X-API-KEY: sk_xxx"

The above command returns JSON structured like this:

  {
    "id": "e4dea538-37d3-40df-99a7-da9992d3300c",
    "key": "very-secure-encrypted-secret/production",
    "value": "this secret is securely stored" 
  }

This endpoint can retrieve a cryptographically secure secret by ID. The secured secret is decrypted and access to this secret will be reflected in the logs.

Get Secret by key

GET https://api.karmahostage.com/secrets?key=very-secure-encrypted-secret/production
X-API-KEY: "sk_xxx"
curl "http://api.karmahostage.com/secrets?key=very-secure-encrypted-secret/production"
  -H "X-API-KEY: sk_xxx"

The above command returns JSON structured like this:

  {
    "id": "e4dea538-37d3-40df-99a7-da9992d3300c",
    "key": "very-secure-encrypted-secret/production",
    "value": "this secret is securely stored" 
  }

This endpoint can retrieve a cryptographically secure secret by path. Paths are easier to work with, as they don't require you to known the ID and can be dynamically generated. The secured secret is decrypted and access to this secret will be reflected in the logs.

Errors

The Karmahostage API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You don't have access to the key or secret
404 Not Found -- The specified secret or key could not be found
405 Method Not Allowed -- You tried to access the API with an invalid method.
418 I'm a teapot.
429 Too Many Requests -- You're making too many requests! Slow down - or upgrade your plan!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.