Auth Create Api Keys

Create Auth Token

POST /v1/keys/auth

Mint an agent auth token. The agent reads this value from the API_TOKEN environment variable and presents it during handshake with the tunnel-server. The full token is returned only once — store it on the agent's host immediately.

Account scope: the token belongs to your active account and may carry traffic for that account's endpoints per your role's permissions. Use switch account to mint a token in a different account.

Bind the token to a specific endpoint (or tunnel) for least-privilege: a per-tunnel token can only carry traffic for that tunnel, so a leak from one machine doesn't expose your other endpoints. Unbound tokens (no endpoint_id) are convenient for development and one-shot tunnels but are powerful — keep them ephemeral.

The Python SDK calls this endpoint internally on every ngris.connect(), mints a new token, runs the agent with it, and revokes the token via DELETE /v1/keys/auth/{id} on shutdown.

Request body

description string

Free-form label. The Python SDK uses the form "ngris-python sdk (http localhost:8080)" so administrators can see "where did this token come from".

endpoint_id int64

Optional. Numeric ID of the endpoint this token may carry traffic for. Without this the token is "unbound" and works for any endpoint owned by the user.

tunnel_id int64

Rare. Bind the token to a single tunnel record. Mostly used internally by the platform.

Response (200 OK)

id int64

Numeric ID. Use to revoke the token via DELETE /v1/keys/auth/{id}.

token string

The full secret. Format: et_at_ + base32 chars. Set on the agent's host as the API_TOKEN environment variable.

Errors

400 Bad Request

Unknown body fields (handler uses strict decoding). Mostly happens if you typo a field name.

401 Unauthorized

Missing auth.

500

Crypto / database error. Safe to retry.

Request
curl -X POST "https://api.ngris.com/v1/keys/auth" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ci-bot agent",
    "endpoint_id": 184
  }'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
tok = client.api_keys.create_auth_token(
    description="ci-bot agent",
    endpoint_id="184",
)
print(tok["token"])  # store; only shown once

Response — 200 OK
{
  "id": 7,
  "token": "et_at_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

PreviousList Auth Tokens NextRevoke Auth Token

On this page

Create Auth Token