Getting Started with the APIs & Command Line Interface

Twingate provides several ways to automate various actions normally carried out via the Admin Panel of the platform.

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:

Select "Read & Write" or "Read, Write & Provision" if you intend to modify objects in Twingate using the CLIs or APIs.Select "Read & Write" or "Read, Write & Provision" if you intend to modify objects in Twingate using the CLIs or APIs.

Select "Read & Write" or "Read, Write & Provision" if you intend to modify objects in Twingate using the CLIs or APIs.

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 a hurry?

Download our Postman Collection and import it in your environment, it contains many examples of API requests including the one below.

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:

Now, right-click on your Collection's name (on the left-hand side) and select add request.

Configure your request as follows:

{
  resources(after: null, first:100) {
    edges {
      node {
        id
        name
        createdAt
        updatedAt
        isActive
      }
    }
    pageInfo {
      startCursor
      hasNextPage
    }
  }
}

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:

  • Change the URL to https://.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

If all is well, you should now be able to click on Docs and should see two new blue links: QueriesRoot and MutationsRoot.

In GraphQL lingo, a Query is an API Request aiming at retrieving information and a Mutation is an API Request aiming at modifying, creating or deleting objects.

Now, click on QueriesRoot then click on Resources, finally click on "ADD QUERY":

You should now see a base query in the body of your request (on the left-hand side):

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).


Did this page help you?