Connection Profiles API

Enterprise

Manage NetStacks Controller connection profiles and their encrypted secrets (passwords, SSH keys, SNMP communities, API tokens) through the API.

Overview

A connection profile holds the login details a device uses: a default username, SSH port, timeouts, automation transport, and a prioritized list of secrets. Every device points at one profile through its profile_id. Secrets are encrypted in the Controller vault, and the API never returns secret values in list or get responses.

These endpoints need credentials.manage. For the concepts and the Admin Console screens, see Credential vault.

Endpoints

Method	Path	Purpose	Permission
`GET`	`/api/profiles`	List profiles	`credentials.manage`
`POST`	`/api/profiles`	Create a profile	`credentials.manage`
`GET`	`/api/profiles/:id`	Get a profile	`credentials.manage`
`PUT`	`/api/profiles/:id`	Update a profile (only the fields you send)	`credentials.manage`
`DELETE`	`/api/profiles/:id`	Delete a profile	`credentials.manage`
`GET`	`/api/profiles/device-counts`	Number of devices using each profile	`credentials.manage`
`POST`	`/api/profiles/assign`	Assign a profile to a list of devices	`credentials.manage`
`GET`	`/api/profiles/:id/secrets`	List a profile's secrets (metadata only)	`credentials.manage`
`POST`	`/api/profiles/:id/secrets`	Add a secret	`credentials.manage`
`PUT`	`/api/profiles/:id/secrets/:secret_id`	Update a secret	`credentials.manage`
`DELETE`	`/api/profiles/:id/secrets/:secret_id`	Delete a secret	`credentials.manage`
`POST`	`/api/profiles/:id/secrets/:secret_id/reveal`	Return the decrypted secret. Body: `{"reason":"…"}` (required, audit-logged)	Profile owner or a `reveal` grant
`GET`	`/api/profiles/:id/grants`	List who may use this profile	`credentials.manage`
`POST`	`/api/profiles/:id/grants`	Grant a user or role access	`credentials.manage`
`DELETE`	`/api/profiles/:id/grants/:grant_id`	Remove a grant	`credentials.manage`
`GET`	`/api/profiles/accessible`	Profiles the caller may use, as `{"items":[…]}`	Signed in
`GET / PUT`	`/api/profiles/accessible/default`	Get or set the caller's default profile	Signed in

Create a profile

curl -s --cacert netstacks-ca.pem -X POST https://controller.example.com:3000/api/profiles \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Core switches", "username": "netops", "ssh_port": 22}'

Field	Type	Notes
`name`	string	Required.
`description`	string	Optional.
`profile_type`	string	`shared` (default), `personal`, or `service`.
`owner_id`	UUID	Owner of a personal profile.
`username`	string	Default login username.
`ssh_port`	integer	SSH port.
`automation_transport / automation_port`	string / integer	For config automation: `gnmi` or `netconf`, and its port.
`cli_flavor`	string	How CLI output is parsed, for example `auto`.
`connection_timeout / keepalive_interval`	integer	Seconds.
`auto_commands`	string[]	Commands to run after connecting.
`is_default / is_service`	boolean	Default-profile and service-profile flags.

The response is 201 with the profile.

Add a secret

Each secret is one way to authenticate. When a connection is made, secrets are tried in priority order (lowest first).

curl -s --cacert netstacks-ca.pem -X POST \
  https://controller.example.com:3000/api/profiles/51a2.../secrets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"secret_type": "password", "username": "netops", "secret": "<password>", "priority": 1}'

Field	Type	Notes
`secret_type`	string	Required. `password`, `ssh_key`, `snmp_community`, `api_token`, or `generic_secret`.
`secret`	string	Required. The password, private key, community string, or token. Encrypted before storage.
`username`	string	Optional. Overrides the profile username.
`passphrase`	string	Optional SSH key passphrase.
`enable_secret`	string	Optional enable / privileged-mode password.
`priority`	integer	Optional. Lower is tried first.
`host / port`	string / integer	Optional.
`allow_port_forwarding, allow_scp_sftp, record_sessions`	boolean	Optional session policy flags.
`expires_at`	timestamp	Optional expiry.
`metadata`	object	Optional.

Keep secrets out of shell history

Read secrets from a file or environment variable instead of typing them on the command line, for example -d @secret.json.

Assign a profile to devices

POST /api/profiles/assign sets profile_id on many devices at once. Send null as profile_id to clear the assignment.

{ "device_ids": ["8d1e...", "a41f..."], "profile_id": "51a2..." }

Access grants

Grants control which users and roles may use a profile. POST /api/profiles/:id/grants takes:

Field	Type	Notes
`grantee_type`	string	`user` or `role`.
`grantee_id`	UUID	The user or role ID.
`permission_level`	string	`use` (default) or `reveal`.