API Overview
Welcome to the Ngris API Reference. This documentation provides comprehensive details on all available endpoints for managing tunnels, domains, traffic policies, and more.
Base URL
All API requests should be made to the following base URL:
Authentication
The API supports two methods of authentication. You can use either a Bearer Token (JWT) or an API Key.
Method 1: API Key (Recommended)
Use an API Key for machine-machine communication. Pass it in the X-API-KEY header.
Get your API key from the dashboard's API Keys page.
Method 2: Bearer Token (JWT)
Use a JWT for temporary user sessions. You can obtain a token via the /auth/login endpoint. Pass it in the Authorization header.
Request bodies
Every POST, PUT and PATCH request must send Content-Type: application/json, even when it has no body (a promote, a revoke, a retry). Without it the API answers 415 Unsupported Media Type with {"error": "Content-Type must be application/json"}. File uploads sent as multipart/form-data (the custom error template upload) are the exception.
Suspended accounts
While the active account is suspended, every request — reads included — answers 403 with {"code": "account_suspended"}, except your own user and settings, the accounts list and switching, the account's status (Get account, entitlements) and billing.
Accounts & Multi-tenancy
You can belong to several accounts, but every request operates inside exactly one active account at a time. Bearer tokens carry an active_account_id claim identifying it; to act in a different account, mint a new token via POST /v1/user/switch-account. See your current active account with GET /v1/account.
Most resources — endpoints, tunnels, domains, certificates, client CAs, dedicated IPs, API keys, agent auth tokens, traffic and firewall policies, usage, stats, and the account audit log — are shared across all members of the active account. What each member may see or change is governed by their role (a named set of permissions); list the available roles with GET /v1/account/roles and the account's members with GET /v1/account/members.
Billing is handled at the account level: the account owner holds the payment method and subscription, and add-ons such as dedicated IPs are billed to the account. Some add-ons also carry a one-time, non-refundable setup fee (for per-region dedicated IPs, charged per region).
IDs
Every object you can address has a uuid, and every reference to another object is a <thing>_uuid field (endpoint_uuid, role_uuid). Paths take the uuid (/v1/tunnels/{uuid}), and request bodies and query strings take the *_uuid names. Plans are addressed by their slug ("plan": "team"). Treat uuids as opaque strings.
Deprecated: integer ids (id, *_id) still work and still appear in responses until the sunset on 2026-11-13 23:59:59 UTC; requests that use them get Deprecation and Sunset headers. After the sunset an integer id is a 400 integer_id_unsupported. See Moving to public IDs (UUIDs).
Rate Limiting
API requests are rate-limited to ensure service stability. Check the headers in the response for your current usage status.
X-RateLimit-Limit: The maximum number of requests allowed in the window.X-RateLimit-Remaining: The number of requests remaining in the current window.X-RateLimit-Reset: The time at which the current rate limit window resets.