Register Agent Keys Security

Register Agent Key

POST /v1/security/agent-keys

Register a key an agent can log its tunnel in with. Get your registration code, sign it with the key (ngris key sign <code>) and send the output as signature. The key then logs in as you, in your active account.

Preview. A key logs in tunnels only: the ngris API, app commands and the agent's edge-protection flags still need a token. See Key authentication.

A key can be registered once on ngris. Sending a key you already registered in this account returns 200 OK with that key, unchanged, and "existing": true, so the call is safe to repeat. A key registered by another member or in another account returns 409: delete it there, or create a new key.

Requires the endpoints:write permission on the active account. Not available with an OAuth/MCP token (use the dashboard or an API key) or while the account is suspended. Available on every plan. Registering a key adds an agent_key entry ("Agent key uploaded") to the account audit log.

Never send a private key. It is refused. A private key you pasted anywhere is no longer secret: create a new one.

Request body

signature string Req

The output of the signing command: the whole -----BEGIN SSH SIGNATURE----- … -----END SSH SIGNATURE----- block, unchanged.

name string

Optional label, up to 100 characters. Without one, the key gets a name such as Agent key SHA256:B5UOOVg/.

Accepted keys

ed25519 (recommended).
RSA with 2048 to 4096 bits.
Not accepted: hardware security keys, SSH certificates, ECDSA and DSA keys. The agent also can't use a key with a passphrase.

Response (201 Created; 200 OK when you already registered the key here)

item object

The key, with the fields of List Agent Keys: uuid, name, key_type, fingerprint, user_uuid, user_name, created_at, last_used_at.

existing boolean

Only with 200: true, you had already registered this key in this account. Nothing was added or changed, and item is the existing key.

Errors

400 Bad Request

The body isn't JSON, or the key or its signature can't be used. error says what to do next. See Common problems below.

401 Unauthorized

Missing auth.

403 Forbidden

The caller lacks endpoints:write; the request uses an OAuth/MCP token (cannot mint long-lived credentials from an OAuth session); the account is suspended (code account_suspended); or your membership or the account changed while the key was being registered (You can't register agent keys in this account right now). Nothing is stored.

409 Conflict

this key is already registered on ngris — delete it there or create a new key for this account: another member or another account registered this key.

Common problems

A private key was sent: it is refused and no longer secret. Create a new key.
The .pub file was sent: send the output of the signing command instead.
The output is cut off or was changed: run the signing command again and send its whole output.
The signature is for another code or another key: get the code for this account, and sign it with the key you are registering.
The key type or size isn't accepted, or the key can't be used: create a new key with ssh-keygen -t ed25519.

Request
# 1. Your registration code
CODE=$(curl -s "https://api.ngris.com/v1/security/agent-keys/statement" \
  -H "X-API-KEY: <your_api_key>" | jq -r .code)

# 2. Sign it with the key you are registering
ngris key sign "$CODE" > agent_key.sig

# 3. Register the key
jq -n --arg name "build server" --rawfile signature agent_key.sig \
     '{name: $name, signature: $signature}' |
curl -X POST "https://api.ngris.com/v1/security/agent-keys" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  --data @-

Request body
{
  "name": "build server",
  "signature": "-----BEGIN SSH SIGNATURE-----\nU1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAg7pjCaIQOjlxjVBrDROsUTXugjc\nSYYrP71oZNt3kgJgkAAAAPbmdyaXMtYWdlbnQta2V5AAAAAAAAAAZzaGE1MTIAAABTAAAA\nC3NzaC1lZDI1NTE5AAAAQOZOZISqHXKisFRNHQQ+Kssj9CkfWz68O4PfckmDWllFi6TZDT\nBQLo4Fr/fWB9v2Y21XsVrIDH9Fd7yD6MrbXgk=\n-----END SSH SIGNATURE-----\n"
}

Response — 201 Created
{
  "item": {
    "uuid": "01a16821-d490-7359-a935-39a84a87074a",
    "name": "build server",
    "key_type": "ssh-ed25519",
    "fingerprint": "SHA256:B5UOOVg/OK1TzCZjPLdToX0T5CqKQgnF5QnsspIW1QM",
    "user_uuid": "019e23c8-7400-716b-abfe-ba4bd3a29ef1",
    "user_name": "Alice Smith",
    "created_at": "2026-10-23T09:40:10Z",
    "last_used_at": null
  }
}

Response — 200 OK (you already registered this key here)
{
  "existing": true,
  "item": {
    "uuid": "01a16821-d490-7359-a935-39a84a87074a",
    "name": "build server",
    "key_type": "ssh-ed25519",
    "fingerprint": "SHA256:B5UOOVg/OK1TzCZjPLdToX0T5CqKQgnF5QnsspIW1QM",
    "user_uuid": "019e23c8-7400-716b-abfe-ba4bd3a29ef1",
    "user_name": "Alice Smith",
    "created_at": "2026-10-23T09:40:10Z",
    "last_used_at": "2026-10-23T09:41:02Z"
  }
}

Response — 403 Forbidden (membership or account changed while registering)
{
  "error": "You can't register agent keys in this account right now"
}

Response — 409 Conflict
{
  "error": "this key is already registered on ngris — delete it there or create a new key for this account"
}

Was this helpful?

PreviousList Agent Keys NextDelete Agent Key

On this page

Was this helpful?