Management REST API

Overview

While the Crypteron Dashboard is an easy to use GUI dashboard, we understand some organizations may want to programmatically interact with their security model. Use cases range from

  1. PCI Compliance: Automatic key rollovers every X months
  2. Multi-tenancy: Automatically provision a new security partitions for new tenants
  3. Data Breach: Automatic pause/resume of your app based on signals from your security information and event management (SIEM) systems

To allow for these complex cases, the Crypteron Dashboard was deliberately designed as a single paged JavaScript application. This allows us to expose the same underlying functionality as a RESTful API to you.

If you enable developer tools in Google Chrome or Firefox, you can see the network interaction between the Crypteron Dashboard and the Crypteron API. Simply press the F12 key and choose the network panel. We recommend filtering by api.crypteron.com in order to remove clutter from any marketing/analytic APIs in use. Now perform the action you desire to automate from within the dashboard - you should see the request-response exchange you need to script.

Prerequisites

Your App ID

To get your App ID, log into the dashboard at https://my.crypteron.com and click on your app. Your App ID will be in the browser URL. For example, if the URL is https://my.crypteron.com/apps/2376 then the App ID is 2376.

API Endpoint

The API is hosted behind a load balancer at https://api.crypteron.com/v1. This is the base URL that you will use. All  traffic is SSL encrypted. NOTE: Self-hosted enterprise customers  have a custom API URL.

Management API Keys

Customers on eligible plans can generate, refresh or delete Management API in their dashboard profile page. Note that the Management API Keys have absolutely nothing to do with the encryption keys within the Crypteron platform - they only allow you to automate your dashboard interactions.

Why Management API Keys?

Browser based user interactions are authenticated using short lived OAuth tokens. However, programmatic or automated access to the dashboard demand another technique since multi-factor authentication makes such automated access very impractical. Plus you wouldn't want to embed your main user credentials inside your code, you want to be able to delegate access that can be easily revoked. To allow this, Crypteron now provisions Management API Keys for secure automation.

Authentication

Authentication is done via HTTP Basic authentication and is fully security via TLS encryption. We're also using Basic authentication the standard way, so the string after Basic in the Authorization header is a base64 string obtained by concatenating the username ("") with a colon (":") and the password (your management API key). For example if your management API key is XCpHpdIimBEWS3TQBAzPgCiYztxaRRiwzNiBAHKB8RBJ-33 the HTTP Authorization header will be

Authorization: Basic <Base64(":XCpHpdIimBEWS3TQBAzPgCiYztxaRRiwzNiBAHKB8RBJ-33")>

or ultimately

Authorization: Basic OlhDcEhwZElpbUJFV1MzVFFCQXpQZ0NpWXp0eGFSUml3ek5pQkFIS0I4UkJKLTMz

Examples

Create a New Security Partition

The HTTP request below will create new security partition called tenant4758 with its own set of encryption keys and access control rules:

Request

POST /v1/keys HTTP/1.1
Host: api.crypteron.com
Accept: application/json, text/plain, */*
Authorization: Bearer <OAuth_token>
Content-Type: application/json;charset=UTF-8

{"AppId":"2376","SecPartId":"tenant4758","Description":"This is tenant 4758"}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /v1/Keys/416

{"KeyId":416,"AppId":2376,"SecPartId":"tenant4758","SecPartVer":1,"Description":"This is tenant 4758","AddedBy":"John Doe <[email protected]>","CreatedAt":"2016-12-08T00:00:13.3357136Z","ModifiedAt":"2016-12-08T00:00:13.3357136Z","Oid":"2.16.840.1.101.3.4.1.46","AccessControlEntries":[{"AceId":472,"RoleId":"default","Permissions":983052,"KeyEntityId":416}]}

Or with the new Management API style which uses Basic authentication over a TLS encrypted tunnel. Note that the string after Basic in the Authorization header is the base64 string obtained by concatenating the empty username ("") with a colon (":") and your 'password' (your management API key).

Request

POST /v1/keys HTTP/1.1
Host: api.crypteron.com
Accept: application/json, text/plain, */*
Authorization: Basic <Base64Encode("" + ":" + "<your management API key>")>
Content-Type: application/json;charset=UTF-8

{"AppId":"2376","SecPartId":"tenant4758","Description":"This is tenant 4758"}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /v1/Keys/416

{"KeyId":416,"AppId":2376,"SecPartId":"tenant4758","SecPartVer":1,"Description":"This is tenant 4758","AddedBy":"John Doe <[email protected]>","CreatedAt":"2016-12-08T00:00:13.3357136Z","ModifiedAt":"2016-12-08T00:00:13.3357136Z","Oid":"2.16.840.1.101.3.4.1.46","AccessControlEntries":[{"AceId":472,"RoleId":"default","Permissions":983052,"KeyEntityId":416}]}

Here is a similar request as a curl command

curl -u :<your management API key> 'https://api.crypteron.com/v1/keys' \ 
-H 'content-type: application/json' \ 
-H 'accept: application/json' \
 --data-binary '{"AppId":"2376","SecPartId":"tenant4758","Description":"This is tenant 4758"}'

As always, please do not hesitate to contact us at [email protected] for any help.

Recent blog posts

Migrating existing live data into Crypteron

You’re already live in production. And you have sensitive in the clear. Read this article to see how Crypteron can help.

Encryption, Entity Framework and Projections

Projections in Entity Framework live outside the entity lifecycle. Read more to learn how your can use Crypteron to secure such data.

PCI DSS and key rotations simplified

PCI compliance requires data encryption keys to be changed frequently. Here is how you can do it easily.

Your data-center is not secure and what you can do about it

There is no secure perimeter anymore. Neither in your corporate network nor in your data center. Fight a winning battle armed with self-protecting data rather than a losing one trying to protecting the infrastructure.

Introducing the Crypteron Startup Innovators Program

Qualifying startups get up to 50% off all plans. Tell us how you’re changing the world and the our Startup Innovators Program will support your journey.

6 encryption mistakes that lead to data breaches

If encryption is so unbreakable, why do businesses and governments keep getting hacked? Six common encryption mistakes that lead to data breaches.

Announcing the new Crypteron Community Edition

Starting today you can now sign up for the Crypteron Community Edition for free with no performance limitations.

Data breach response – One click to save your business

Get breathing room – when you need it the most. Respond to a data breach with a single click.

Why We Need Proper Data-At-Rest Encryption: 191M U.S. Voters’ Data Exposed

Adding security at the application level is a large step forward in protecting data from the constant threat of data breaches

How to encrypt large files

CipherStor is blazingly fast! Here we show how to use it within your data-flow pipeline to maintain high performance when encrypting large files.