twingate-api

Role

This skill owns Twingate's GraphQL API, service account key management, CLI tooling, and API-driven automation. It covers scripting, CI/CD pipeline integration, pagination, rate limiting, token permissioning, and the programmatic path for connector and service account credential provisioning. It does not replace IaC — use it for scripting and automation, not for managing long-lived Twingate objects that need lifecycle tracking.

Decisions & Guidelines

• Always check ok before reading entity in a mutation response. A mutation can return HTTP 200 with ok: false and entity: null. Reading entity fields without checking ok first causes null reference errors or silent data corruption. Check error.errorCode and error.message on failure.
• Always paginate — never assume all results fit in one page. Scripts that omit pagination silently miss records with no error. You may get 50 of 500 resources. Loop on pageInfo.hasNextPage until false, passing pageInfo.endCursor as the after argument on each request.
• Never parse, decode, or construct IDs. Twingate IDs are opaque base64-encoded NodeIDs. Use them only as returned by the API. Never infer numeric components from base64 decoding.
• Issue the least-privileged token for the task. Read for monitoring/reporting. Write for provisioning. Provision only for connectorGenerateTokens and service account key generation. Never issue Provision-level tokens to read-only scripts.
• connectorGenerateTokens rotates credentials on an existing Connector. Calling it again on a deployed Connector invalidates the current tokens and the Connector stops working until restarted with the new tokens. Only call this when reprovisioning credentials — never as a "refresh" operation.
• Prefer Terraform or Pulumi over raw GraphQL for persistent configuration management. The API is the right tool for scripting, automation, and reporting. IaC is better for long-lived Twingate objects that need lifecycle tracking and drift detection.
• Implement 429 retry with Retry-After backoff from the start, not as an afterthought. The API enforces per-minute rate limits. Scripts that ignore 429 fail mid-run on large operations. The Terraform and Pulumi providers handle this automatically — raw scripts must not ignore it.
• Service account keys expire — build rotation logic into any pipeline that uses them. Monitor expiresAt and rotate before expiry. Reactive rotation on failure disrupts pipelines.
• There are two unrelated tools both called "the Twingate CLI" — do not conflate them. Twingate-Labs/tg-cli (Deno/TypeScript; export/import, topology diagrams) and Twingate-Labs/Twingate-CLI (Python, installed as tgcli; full CRUD, multi-tenant sessions) are separate projects with different flags and no shared history. Confirm which one the user means before giving command syntax. Flag repos like gh-twingate-solutions-general-scripts.md as LLM-assisted reference examples, not supported products, before recommending them for production use.

Search References First