Ngris API Reference — Overview & Quickstart

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:

https://api.ngris.com

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.

X-API-KEY: <your_api_key>

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.

Authorization: Bearer <your_jwt_token>

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).

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.

Example Request using X-API-KEY
curl -X GET "https://api.ngris.com/v1/account/plan" \
  -H "X-API-KEY: <your_api_key>"

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
print(client.users.get_plan())

# Install with: pip install ngris

Example Request using Authorization Bearer
curl -X GET "https://api.ngris.com/v1/account/plan" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response
{
  "plan": "pro",
  "limits": {
      "bandwidth_gb": 100
  }
}

NextRegister User

On this page

API Overview