Twingate provides several ways to automate various actions normally carried out via the Admin Console. All the methods mentioned below can be used independently or integrated into orchestration platforms (Ansible, Chef, Puppet, etc.):

• A set of GraphQL APIs
• A Python based Command Line Interface (CLI)
• A javascript based Command Line Interface (CLI)

Getting Started

Technically speaking, the Command Line Interfaces (CLIs) leverage the Twingate APIs so whether you chose to use the CLIs or the APIs directly, you will first need two things:

• A valid Twingate API Key
• A valid Twingate Tenant Name (This requires signing up for a tenant on twingate.com, if you read this guide, you likely already have it.)

Generating an API Key

Open the Admin Panel of Twingate and head over to Settings; over on the left-hand side, click on API.

Create a new Token by clicking Generate Token:

Once your Token is generated, copy it and store it somewhere safe (Note: you will not be able to retrieve the Token from the Twingate interface once you close the “Generate Token” window.)

What You Need To Test The APIs

The best way to start experimenting with the Twingate GraphQL APIs is by using a lightweight API client.

We recommend using either:

• Postman (Great if you are already familiar with Rest APIs)
• Altair GraphQL Client (Great if you are not familiar with Rest APIs or GraphQL APIs)

Don’t worry too much about which one you pick, they are both user friendly, free and covered below.

Now, let’s dive a bit deeper and start with a simple API call: we will retrieve the list of all Twingate Resources from our Twingate account.

Retrieving The List Of Twingate Resources (with Postman)

In Postman, create a new Collection, click on it and go to the Authorization tab. Under Key, select X-API-KEY and under Value copy-paste your Twingate API Token:

Still while highlighting the Postman Collection, move to the Variables tab and add a new variable called tenant_name: give it your own Twingate tenant name as a value:

Great! You have created your first API query. Time to run it!

Click on the Send button and wait for the call to return a response. If all goes well, you should see a response that will look like the following:

{
    "data": {
        "resources": {
            "edges": [
               {
                    "node": {
                        "id": "UmVzb3VyY2U6MjU3Mg==",
                        "name": "AWS SSH",
                        "createdAt": "2021-01-20T15:54:53.046611+00:00",
                        "updatedAt": "2022-05-06T21:14:45.766635+00:00",
                        "isActive": true
                    }
                },
                {
                    "node": {
                        "id": "UmVzb3VyY2U6MjkxMw==",
                        "name": "AWS Grafana Admin",
                        "createdAt": "2021-02-09T02:41:48.605518+00:00",
                        "updatedAt": "2021-10-05T02:08:13.938672+00:00",
                        "isActive": true
                    }
                }
            ],
            "pageInfo": {
                "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
                "hasNextPage": false
            }
        }
    }
}

In a typical GraphQL response, each returned object is presented as a node and collections of nodes are presented as edges, hence the structure of the output.

Notice anything interesting? The structure of the response seems to match the fields we specified in our own query: this is specific to GraphQL, it is a query system that allows users to craft specific queries (in order to limit the computing power required server-side to process a request).

Retrieving The List Of Twingate Resources (with Altair GraphQL Client)

Open Altair GraphQL Client and in a new window (replace subdomain with your own subdomain):

• Change the URL to https://subdomain.twingate.com/api/graphql/ (use your own Tenant name)
• Set a Header with the name X-API-KEY and copy-paste your Twingate API token as a value

• Now, click on QueriesRoot then click on Resources, finally click on ”ADD QUERY“:

Notice the node highlighted in red? Go ahead and replace node with the following JSON:

node{
   id
   name
}

Your query should now look like this:

Great! No more red highlights, this means the body of our query is consistent with the API schema. Now click on (Run query) and watch the output of the API request:

In a typical GraphQL response, each returned object is presented as a node and nodes are collections of nodes are presented as edges, hence the structure of the output.

Notice anything interesting? The structure of the response seems to match the fields we specified in our own query: this is specific to GraphQL, it is a query system that allows users to craft specific queries (in order to limit the computing power required server-side to process a request).