CT-VL Admin REST APIs

The CT-VL Administration REST API allows you to manage the administration of the CT-VL. After completing the administrative tasks, you will be able to run the tokenize and detokenize data commands.

To use the Admin REST API you must be using:

• The CT-VL Server version 2.6.0 or newer.

• A CipherTrust Manager version compatible with CT-VL 2.6.0.

Base URL

The following is the base URL for Admin REST API operations:

https://<server_address>/api/

Authentication

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or MACed and/or encrypted.

By default, JWT authentication expires in 10 minutes. This setting can be changed using the CLI, under the auth menu.

Retrieve a Token Request

Request

curl -X POST \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Password123!"}' \
https://{server_address}/api/api-token-auth/

Response

{ "token": "eyJ0eXA [...] KnA74" }

Refresh a Token Request

Request

curl -X POST \
-H "Content-Type: application/json" \
-d '{"token":"<EXISTING_TOKEN>"}' \
https://{server_address}/api/api-token-refresh/

Response

{ "token": "eyJ0eXA [...] KnA74" }

Responses

This section describes request response codes and response pagination details.

Response Codes

HTTP status codes are grouped into five categories:

• 1xx for informational

• 2xx for success

• 3xx for redirection

• 4xx for client errors

• 5xx for server errors

Pagination

Requests that return multiple items will be paginated to 25 items.

Responses include a count field, which specifies the total number of objects available via pagination. Responses also include a next and previous field. If count is superior to 25, these fields contain a URL path to access the objects located respectively after or before.

Request

GET https://{{server_address}}/api/v1/users/?limit=100&offset=400

Response

HTTP 200 OK
{
"count": 1023
"next": "https://{server_address}/api/users/?limit=100&offset=500",
"previous": "https://{server_address}/api/users/?limit=100&offset=300",
"results": [ … ]
}

Operations

The CT-VL Admin REST API supports the following operations:

Searching

To search objects, add the attribute ?search= at the end of the URL followed by the pattern you want to look for. All the objects containing that pattern in one of their attributes will be included in the Response.

Request

GET https://{{server_address}}/api/users/?search=robert
GET https://{{server_address}}/api/groups/?search=finance

Ordering

To query object in a specific order, add the attribute ?ordering= at the end of the URL followed by the attribute you want to order by.

Ordering Examples

Order users by username:

GET https://{{server_address}}/api/v1/users/?ordering=username

You may also specify reverse orderings by prefixing the field name with '-', like so:

GET https://{{server_address}}/api/v1/users/?ordering=-username

Multiple orderings may also be specified:

GET https://{{server_address}}/api/v1/users/?ordering=username,email

Object Format

The response format for all requests is a JSON object.

Creating Objects

To create a new object, send a POST request to the class URL containing the contents of the object. For example:

curl -X POST \
    -H "{'Authorization':'Bearer '+<token>}" \
    -H "Content-Type: application/json" \
    -d '{"name":"User1", ...}' \
    https://{server_address}/api/{some_ressource}/

Retrieving Objects

To retrieve a list of objects, send a GET request to the class URL. For example:

curl -X GET \
-H "{'Authorization':'Bearer '+<token>}" \
-H "Content-Type: application/json" \
https://{server_address}/api/{some_ressource}/

Updating Objects

To edit an object, send a PUT request to the URL containing the new content with the object's ID. For example:

curl -X PUT \
    -H "{'Authorization':'Bearer '+<token>}" \
    -H "Content-Type: application/json" \
    -d '{"name":"User1", ...}' \
    https://{server_address}/api/{some_ressource}/:id

Deleting Objects

To delete an object, send a DELETE request to the class URL with the object's ID. For example:

curl -X DELETE\
    -H "{'Authorization':'Bearer '+<token>}" \
    -H "Content-Type: application/json" \
    https://{server_address}/api/{some_ressource}/:id

Backing up CT-VL

Schedule automatic backups of the CT-VL.

GET https://<IP_Address>/api/backup/create

This request must be preceded by a successful authentication request. Use the secure token provided with the response in the portion of this example..

Set Backup Endpoint Details

Example cURL Requests

Authentication

curl -X POST\
    -H "Content-Type: application/json" \
    -d ‘{username”:”ctsuser”,”password”:”Password123!”}’ \
    https://cts_server_address/api/api-token-auth

Backup Request

curl -X GET\
    -H ‘{Authorization”::”Bearer <token>”}’\
    -d ‘{username”:”ctsuser”,”password”:”Password123!”}’ \
    https://cts_server_address/api/backup/create -o backup.zip

Unauthenticated Healthcheck

Description

Use the healthcheck endpoint to get the status of the CT-VL. This endpoint integrates with load balancers to ensure all the daemons are running, and the tokenization server is healthy. An HTTP response code not equal to 200 indicates failure in CT-VL. The HTTP response also provides a display of status of all services, in JSON format.

Healthcheck Endpoint Details

The unauthenticated healthcheck response parameters and their respective types are described in the table below:

Unauthenticated Healthcheck Response Parameters

Healthcheck Example

Example Request

curl -k -X GET https://IP_Address/healthcheck

Example Response

HTTP/1.1 200 OK
Date: Thu, 29 Oct 2020 22:51:16 GMT
Content-Type: application/json
Content-Length: 310
Connection: keep-alive
Server: CT-VL server
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Pragma: no-cache
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Content-Security-Policy: default-src 'self'
{
"services": [
    {
        "name": "vtsauthz",
        "status": "Started"
    },
    {
        "name": "vaed",
        "status": "Started"
    },
    {
        "name": "uwsgi",
        "status": "Started"
    },
    {
        "name": "nginx",
        "status": "Started"
    },
    {
        "name": "kmd",
        "status": "Started"
    },
    {
        "name": "iam",
        "status": "Started"
    },
    {
        "name": "cryptod",
        "status": "Started"
    }
],
"status": "Started"
}