MSP Partner API

Overview

The MSP Partner API is a GraphQL API for Twingate resellers and managed service providers. It works across every network you manage, so you can:

• List all of your MSP Portals and Customer Networks in one call.
• Pull the plan and license count for each Customer Network into your billing, PSA, or CRM.
• Create a new MSP Portal and invite its first admin from your own onboarding flow.

The API has three queries and one mutation. It cannot update or delete anything, and it cannot create Customer Networks. Create Customer Networks in the MSP Portal. They then appear in the API automatically.

Concepts

Getting started

Credentials

Every request needs two headers. Both values are issued by Twingate. To request them, contact partnersupport@twingate.com.

Endpoint

Call the API from server-side code only. It does not return CORS headers for third-party origins, so requests from a browser fail, and a key in browser code is exposed to anyone using the page.

We recommend setting a User-Agent header with your integration’s name and version, for example acme-psa-sync/2.1.0. It helps Twingate support find your requests.

First request

Use the partner query to check your credentials:

curl https://api.us2.twingate.com/partners \
  -H 'Content-Type: application/json' \
  -H "X-PARTNER-ID: $TWINGATE_PARTNER_ID" \
  -H "X-API-KEY: $TWINGATE_PARTNER_API_KEY" \
  -d '{"query":"{ partner { id name } }"}'

A successful request returns your Partner record:

{"data": {"partner": {"id": "UGFydG5lcjox", "name": "Example Reseller Inc."}}}

A 401 response means a header is missing or incorrect. See Troubleshooting.

GraphQL clients

GraphQL clients such as Altair, Postman, and Insomnia can send requests to the API. Set the URL to your API URL (for example https://api.us2.twingate.com/partners), add the X-PARTNER-ID and X-API-KEY headers, and load the schema for autocomplete. The schema is available in SDL and introspection formats from partnersupport@twingate.com, along with an integration playbook that includes sample queries, client code, and a local mock server.

Operations

partner

Returns the Partner that owns the API key. Use it to check credentials or as a health check.

{
  partner {
    id
    name
    createdAt
    updatedAt
  }
}

networks

Lists the MSP Networks and Customer Networks under your Partner. Disabled networks are excluded. Use filter to return one network type:

networks(filter: { networkType: { in: [MSP] } })              # MSP Networks only
networks(filter: { networkType: { in: [CUSTOMER_NETWORK] } }) # Customer Networks only
networks                                                      # Both types

networks returns a union of MspNetwork and CustomerNetwork. Select fields with inline fragments, and use __typename to tell the two apart:

{
  networks(first: 50) {
    edges {
      node {
        __typename
        ... on MspNetwork {
          id
          name
        }
        ... on CustomerNetwork {
          id
          name
          parent {
            name
          }
        }
      }
    }
  }
}

network

Returns one network by ID, or null if the ID does not belong to your Partner. An ID of another type, or a value that is not an ID, returns an error. Unlike networks, network also returns disabled networks.

query GetNetwork($id: ID!) {
  network(id: $id) {
    __typename
    ... on MspNetwork {
      id
      name
      url
    }
    ... on CustomerNetwork {
      id
      name
      url
      subscription {
        planType
        licenses
      }
    }
  }
}

mspNetworkCreate

Creates a new MSP Network (MSP Portal) and invites its first admin.

mutation {
  mspNetworkCreate(
    networkSlug: "acmemsp"
    networkName: "Acme MSP"
    adminEmail: "it@acme.com"
  ) {
    ok
    error
    entity {
      id
      name
      url
    }
  }
}

The new MSP Network is on the Business plan and uses social sign-in. The admin receives a welcome email and an invitation that requires email verification.

Validation errors return HTTP 200 with ok: false and a message in error, so always check ok:

{"data": {"mspNetworkCreate": {"ok": false, "error": "Network slug is taken.", "entity": null}}}

Types

Partner

MspNetwork

CustomerNetwork

Subscription

licenses is the number of active users plus active Service Accounts, minus active admins, with a minimum of 1. Admins are not billed, so licenses is the billable number. See MSP Billing.

User

Enums

IDs

IDs are opaque strings. Store them as they are returned and use them as keys in your own systems. Do not decode or construct them. Match records on IDs, not names, because names can change.

Pagination

networks, customerNetworks, and adminUsers use Relay-style cursor pagination:

query ListCustomers($after: String) {
  networks(filter: { networkType: { in: [CUSTOMER_NETWORK] } }, first: 50, after: $after) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        ... on CustomerNetwork {
          id
          name
          subscription {
            planType
            licenses
          }
          parent {
            id
            name
          }
        }
      }
    }
  }
}

• Send the query with first: 50 and no after value.
• Process edges.
• If pageInfo.hasNextPage is true, send the query again with after set to pageInfo.endCursor.
• Repeat until hasNextPage is false.

The server caps page sizes, so always loop on hasNextPage instead of assuming one page holds every result. totalCount is the number of matching items across all pages. Use last and before to page backwards.

Nested connections, such as customerNetworks inside networks, paginate separately. To list every Customer Network, use the flat networks query filtered to CUSTOMER_NETWORK shown above. It needs only one loop.

Common workflows

Portfolio dashboard

Show every MSP Network with its customer count, licenses per plan, and admins:

query ListMspNetworks($after: String) {
  networks(filter: { networkType: { in: [MSP] } }, first: 50, after: $after) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        ... on MspNetwork {
          id
          name
          url
          aggregatedSubscriptions {
            planType
            licenses
          }
          customerNetworks(first: 1) {
            totalCount
          }
          adminUsers(first: 25) {
            edges {
              node {
                email
              }
            }
          }
        }
      }
    }
  }
}

customerNetworks(first: 1) { totalCount } returns the customer count without fetching every customer. Cache dashboard results for a few minutes. License counts do not change from second to second.

Monthly billing export

Use the paginated Customer Network query in Pagination to write one row per customer with its MSP Network, plan, and license count.

• If subscription is null, the customer’s plan is still being set up. Mark it as pending and check again later.
• To check the export, compare your totals per MSP Network with that MSP Network’s aggregatedSubscriptions. If they differ, a customer changed during the run. Run the export again.
• Save each export with the date in its file name as a record of what you billed.

Change tracking

The API returns current state only. To track changes, save a snapshot of the billing export keyed by Customer Network id on each run, and compare it with the previous snapshot:

PSA or CRM sync

Store each Customer Network id on the matching account in your PSA or CRM, for example in a custom field. On a schedule, run the billing export query and update the license quantity on each mapped account. Skip customers whose subscription is null until the plan is set.

Provisioning MSP Networks

To create MSP Portals from your own onboarding flow:

• Convert the slug locally the same way Twingate does: remove every character that is not a letter or number, then convert to lowercase. Use the converted slug in every later step.
• List your MSP Networks and check that no url starts with https://<converted slug>..
• Ask a person to confirm, and show them the converted slug. The call creates a live network and sends an email.
• Call mspNetworkCreate once with the converted slug.
• Check ok. If it is false, show error to the user.
• Check that the subdomain of entity.url matches the converted slug.
• Save entity.id and entity.url against the account you are onboarding.
• Tell the admin to expect an invitation email.

Monitoring

Every 15 to 60 minutes, send { partner { id } } from the same environment and with the same key as your scheduled jobs. Alert on a 401 response, repeated timeouts, or a null value for data.partner.

Errors and limits

Errors

An HTTP 200 response does not mean every field resolved. Check for errors on every response, even when data is present.

Limits

Retries

• Retry queries on 429, 502, 503, 504, and network errors with exponential backoff, for example after 1, 2, and 4 seconds.
• Never retry mspNetworkCreate automatically. Check whether the network exists first.
• Set a timeout on every request. 30 seconds is a reasonable default.

Security

• Keep the API key on your server. Never include it in a browser app, mobile app, desktop tool, or a client-side environment variable such as NEXT_PUBLIC_*.
• Store the key in a secrets manager, not in source code, committed configuration files, or shared documents.
• Use a separate key for each system, for example one for billing and one for a dashboard, so you can replace one without affecting the other. To request additional keys, contact partnersupport@twingate.com.
• To rotate a key, request a new key, deploy it everywhere, confirm it works, then ask Twingate to revoke the old key. Revocation is permanent.
• If a key is exposed, contact partnersupport@twingate.com to revoke it immediately.
• Require sign-in on any internal tool that can create MSP Networks.

Troubleshooting

When you contact support, include the time and timezone, the operation name, the HTTP status, and the response body. Never include your API key.

→ Managed Service Providers

→ MSP Billing