API

Overview

Twingate provides an Admin API that is GraphQL-based, allowing you to manage your Twingate network programmatically. It covers:

• Remote Networks, Connectors, and Gateways
• Resources, including Kubernetes, SSH, and web app Resources, and their access assignments
• Groups, Users, Devices, and device posture
• Security Policies and DNS filtering profiles
• Service Accounts and Service Keys
• Access requests, SSH certificate authorities, and serial numbers

API schema documentation is part of the GraphQL API endpoint and is always up to date. See Getting started to generate an API token.

Quick reference

Replace <subdomain> with your Twingate network’s subdomain (for example, acme for acme.twingate.com).

curl -X POST "https://<subdomain>.twingate.com/api/graphql/" \
  -H "X-API-KEY: <your API token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ remoteNetworks(first: 10) { edges { node { id name } } } }"}'

Getting started

In order to access the GraphQL endpoint for your Twingate network, you first need to generate an API token in the Admin console. To generate an API token, log into the Admin Console and navigate to Settings > API > Generate Token as seen in the screenshot below.

The API section of Settings, showing tokens with Read only, Read & Write, and Read, Write & Provision permission levels.

After generating an API key, you can either modify its details or disable and enable it as needed.

Token permissions

Each API token is assigned a permission level when it is created. Each level includes everything the level above it allows.

Grant each token the lowest level it needs.

Allowed ranges

You can optionally restrict a token to specific source addresses. Requests made from an address outside a token’s allowed ranges fail authentication.

• Up to 10 entries per token, each either a CIDR range or a single IP address.
• Defaults to 0.0.0.0/0, ::/0, which allows requests from any address.
• IPv4 and IPv6 are both supported.

Once you have your API token, send requests to the endpoint with your token in the X-API-KEY header. See Quick reference for the endpoint, header, and an example request.

Example query

If you’re new to using GraphQL, this example query requests the first 10 Remote Networks in your account, returning the ID and name of each Remote Network along with pagination information if there are more results. Additional information can be returned for each RemoteNetworkEdge node; consult the GraphQL schema for more information.

{
  remoteNetworks(after: null, first:10) {
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      startCursor
      hasNextPage
    }
  }
}

GraphQL clients

If you’re looking for a query GUI, GraphiQL is very easy to use. You can get started quickly on Mac with Homebrew:

brew install --cask graphiql

Another popular open source client is Altair.

If you’re using Python, we’d recommend the gql library, which allows you to get started with just a few lines of code and a query string.

API Schema

The API schema (both the available endpoints and type definitions) can be retrieved by introspection. Some clients such as Altair have built-in tools to perform introspection queries and present formatted documentation for developers to be able to navigate the API:

Terraform Provider

Twingate’s Terraform provider uses the Twingate API to automatically provision Twingate constructs such as Connectors and Resources, and may be useful if you’d like to manage your organization’s infrastructure as code. Please see the documentation for more details as well as the Terraform - Getting Started guide.

Should your Terraform run fail to complete due to a 429 response status code, check the version of your Twingate provider and upgrade to the latest version to ensure the Twingate provider appropriately handles retries when reaching the API throttling limits.

API Throttling

Twingate limits the number of API requests based on the number of read or write requests per minute. The default limits set per account are shown below. Should these limits be reached within a 1 minute window, Twingate will return a 429 response status code to retry again the time period specified in the response.

Last updated 6 days ago