1. Overview

The Twistlock API is exposed on the host that runs Console on ports 8081 (HTTP) and 8083 (HTTPS). These ports are specified at install time in twistlock.cfg.

The preferred path to the API is over HTTPS on https://<CONSOLE_HOSTNAME>:8083/api/v1.

Access to the API requires authentication. You can either:

  • Retrieve a token, then pass the token in the Authorization field of all subsequent requests.

  • Use Basic HTTP authentication for each request.

2. Accessing the API using token authentication

To access the API using a token:

Procedure

  1. Retrieve a token from the api/v1/authenticate endpoint with your user credentials. Tokens are valid for 24 hours. You can also retrieve tokens using client certificates.

    $ curl -H "Content-Type: application/json" \
       -d '{"username":"admin", "password":"admin"}' \
       https://<TWISTLOCK_CONSOLE>:8083/api/v1/authenticate
    {
     "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }

    If you integrated Twistlock Console with Active Directory, and you’re using the sAMAccountName user identifier, escape the backslash in the DOMAIN\sAMAccountName username value. For example:

    $ curl -H "Content-Type: application/json" \
       -d '{"username":"DOMAIN\\admin", "password":"admin"}' \
       https://<TWISTLOCK_CONSOLE>:8083/api/v1/authenticate
    {
     "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }
  2. Call the Twistlock API, submitting the token in the Authorization field in the HTTP header of your request. For example, test connection to the API using the /api/v1/policies endpoint:

    $ curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
      https://<TWISTLOCK_CONSOLE>:8083/api/v1/policies/runtime/container

3. Accessing the API using Basic authentication

The basic token is a Base64 encoded string of type username:password.

Procedure

  1. Generate the Base64 encoding of your username and password. Assume your username is api, and your password is api.

    $ echo -n "api:api" | openssl base64
    YXBpOmFwaQ==
  2. To access any other endpoint, set the Authorization field of your HTTP header to Basic and add the encoded string. For example, to get all your runtime container policies:

    $ curl -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
       https://<TWISTLOCK_CONSOLE>:8083/api/v1/policies/runtime/container

4. Accessing the API using a client certificate

You can retrieve a token using client certificates issued by your public key infrastructure.

Request a token using your private key (cert.key) and public certificate (cert.crt). For simplicity, you can combine both private key and public cert into a single PEM file.

Prerequisites

Procedure

  1. (Optional) Create a single PEM file by concatenating your public certificate and private key.

    Both input files must be in PEM format already.

    $ cat cert.crt cert.key > cert.pem
  2. Run the curl command to retrieve a token with its associated role.

    With a single PEM file:

    $ curl -k \
      -X POST \
      --cert cert.pem \
      https://<console>:8083/api/v1/authenticate-client
    {
     "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","role":"admin"
    }

    With individual public certificate and private key files:

    $ curl -k \
      -X POST \
      --cert cert.crt --key cert.key \
      https://<console>:8083/api/v1/authenticate-client
    {
     "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","role":"admin"
    }
  3. Call the Twistlock API, submitting the token in the Authorization field in the HTTP header of your request. For example, to get all policies:

    $ curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
      https://<TWISTLOCK_CONSOLE>:8083/api/v1/policies/runtime/container