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

To access the GraphQL endpoint for your Twingate network, generate an API token: sign in to the Admin Console and navigate to Settings > API > Generate Token, as seen in the screenshot below.

After generating an API token, you can 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. You can request additional fields for each RemoteNetwork node. See API schema for how to explore all available fields.

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

GraphQL clients

If you’re looking for a query GUI, Altair is a popular open source GraphQL client. Postman also supports GraphQL requests. Getting Started with the API walks through both.

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. See the provider documentation and the Terraform getting started guide for details.

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. If a limit is reached within a 1-minute window, Twingate returns a 429 response status code. Retry the request after the time period specified in the response.