List Auth Tokens

GET /v1/keys/auth

List all agent auth tokens of your active account. These are the credentials the agent logs in with (ngris auth --token or the API_TOKEN environment variable). Distinct from account-level API keys (used for REST authentication via X-API-KEY). An agent can also log its tunnel in with a key instead of a token: see agent keys (Preview).

Account scope: agent auth tokens belong to your active account and are shared with its members per your role's permissions. Use switch account to manage tokens in a different account.

A token can be bound to a specific endpoint or tunnel — the tunnel-server validates the binding at handshake and rejects if mismatched. Unbound tokens (no endpoint_uuid) work for any endpoint owned by the user; useful for ephemeral / one-shot tunnels created via ngris.connect().

Query parameters

page int
Optional. 1-based page number. When sent, the response also carries total, page and page_size; when omitted, every token is returned.
page_size int
Optional. Tokens per page when page is sent. Default 15, capped at 200.
q string
Optional. Substring match on description.
status string
Optional. Exact status (active or revoked).
scope string
Optional. endpoint (bound to an endpoint), tunnel (bound to a tunnel) or any (unbound).

Response (200 OK)

items array
Tokens ordered by created_at DESC. [] when there are none.
total, page, page_size int?
Only when page was sent: the number of matching tokens across all pages, the page returned and the effective page size.
items[].uuid string (uuid)
The token's public id. Used in DELETE /v1/keys/auth/{uuid}.
items[].user_uuid string (uuid)
The user who minted the token.
items[].token string
Always "****": the token is stored only as a hash and can't be shown again. The full token is returned once, by create.
items[].description string
Free-form label.
items[].endpoint_uuid string (uuid)?
Endpoint this token is bound to. Omitted = usable on any endpoint of the account.
items[].tunnel_uuid string (uuid)?
Tunnel this token is bound to. Rare — most tokens are endpoint-scoped or unbound. Omitted when unbound.
items[].status string
active | revoked. Revoked tokens are kept in the table for audit purposes but won't authenticate.
items[].created_at datetime
RFC 3339 UTC timestamp.
items[].last_used_at datetime?
Updated whenever an agent successfully handshakes with this token. Omitted for a token that was never used.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Errors

401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/keys/auth" \ -H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") toks = client.api_keys.list_auth_tokens() for t in toks["items"]: binding = f"endpoint:{t['endpoint_uuid']}" if t.get("endpoint_uuid") else "unbound" print(f"{t['uuid']} {t['description']} ({binding}, {t['status']})")
Response — 200 OK
{ "items": [ { "uuid": "019ae915-a554-7fc4-aea3-9c9ce2dd2976", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "token": "****", "description": "ci pipeline", "endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "status": "active", "created_at": "2026-04-29T10:00:00Z", "last_used_at": "2026-04-29T12:34:56Z" }, { "uuid": "019af55d-8406-7d1a-9732-adad45beac07", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "token": "****", "description": "ngris-python sdk (http localhost:8080)", "status": "active", "created_at": "2026-04-28T09:00:00Z" } ] }
Was this helpful?
On this page
List Auth Tokens
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard