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

PCI Compliance: Automatic key rollovers every X months
Multi-tenancy: Automatically provision a new security partitions for new tenants
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 with your Crypteron dashboard are secured using short lived OAuth obtained JWT tokens. However, programmatic or automated access to the dashboard demands another technique since short lived tokens or multi-factor authentication makes automated access very impractical. In addition, you never want to embed your user credentials inside your code. You instead want to be able to delegate access that can be easily revoked and easily scripted with readily available tools (e.g. curl).

Authentication

Authentication is done via HTTP Basic authentication and is fully secured with TLS 1.2 encryption. This gives you great flexibility in scripting management events over a REST API without loss of security. As per the Basic authentication spec, 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 <user@server.com>","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 <user@server.com>","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 support@crypteron.com for any help.