# API

## Overview

Twingate provides an Admin API that is [GraphQL](https://graphql.org/learn/queries/)-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](/content/docs/api-overview#getting-started/index.html) to generate an API token.

### Quick reference

|  | Value |
| --- | --- |
| Endpoint | `https://<subdomain>.twingate.com/api/graphql/` |
| Method | `POST` |
| Header | `X-API-KEY: <your API token>` |

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

```shell
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.

| Level | What it adds |
| --- | --- |
| `Read only` | Read access to everything the API exposes. |
| `Read & Write` | Creating, updating, and deleting. |
| `Read, Write & Provision` | Generating Connector tokens and creating Service Keys. |

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](/content/docs/api-overview#quick-reference/index.html) 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.

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

## GraphQL clients

If you’re looking for a query GUI, [GraphiQL](https://github.com/graphql/graphiql) is very easy to use. You can get started quickly on Mac with Homebrew:

```shell
brew install --cask graphiql
```

Another popular open source client is [Altair](https://altairgraphql.dev/).

If you’re using Python, we’d recommend the [gql](https://github.com/graphql-python/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](https://graphql.org/learn/introspection/). Some clients such as [Altair](https://altairgraphql.dev/) 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](https://registry.terraform.io/providers/Twingate/twingate/latest) 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](https://registry.terraform.io/providers/Twingate/twingate/latest/docs) for more details as well as the [Terraform - Getting Started](/content/docs/terraform-getting-started/index.html) 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](https://github.com/Twingate/terraform-provider-twingate/releases) 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.

| Request type | Request Limit (per minute) |
| --- | --- |
| Reads | 60 |
| Writes | 20 |

Last updated 6 days ago