Uploading SSH Keys to User

Use these endpoints to:

• log in and establish an API session
• list existing users and retrieve their IDs
• create a user with a password
• add an SSH public key to that user

SSH key assignment is currently a 2-step flow. Create the user first, then add the SSH key in a separate request.

Authentication

You can authenticate either with a session cookie or with a personal access token (PAT).

POST /api/login

Headers: Content-Type: application/json

Body:

JSON

{
  "username": "admin",
  "password": "ExamplePassword123!"
}

Example:

Bash

curl -k -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"ExamplePassword123!"}' \
  https://<host>/api/login

The response sets the SPID session cookie. Reuse it with -b cookies.txt in later requests.

PAT Authentication

The API also accepts a PAT in the Authorization header:

Bash

-H "Authorization: Bearer <token>"

To create a PAT for a user:

POST /api/users/userId/token

Example using an existing session cookie:

Bash

curl -k -b cookies.txt \
  -X POST \
  https://<host>/api/users/7/token

Example response (200 OK):

JSON

{
  "accessToken": "abc123exampletoken"
}

Once created, that token can be used instead of cookies.txt:

Bash

curl -k \
  -H "Authorization: Bearer <token>" \
  https://<host>/api/users

Permissions

• GET /api/users requires a role with user list view permission.
• POST /api/users requires a role with user modification permission.
• POST /api/users/userId/sshKey requires user modification permission, or the authenticated user must match userId.

Endpoints

GET /api/users

Returns the current user list, including each user's id, username, and sshKeys.

Example using a session cookie:

Bash

curl -k -b cookies.txt https://<host>/api/users

Example using a PAT:

Bash

curl -k \
  -H "Authorization: Bearer <token>" \
  https://<host>/api/users

Example response (200 OK):

JSON

[
  {
    "username": "admin",
    "id": "1",
    "roleId": 1,
    "sshKeys": []
  },
  {
    "username": "craig",
    "id": "7",
    "roleId": 2,
    "sshKeys": [
      {
        "sshKeyName": "craig-laptop",
        "sshKeyFingerprint": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
        "userId": "7"
      }
    ]
  }
]

If jq is available, you can extract a user ID directly:

Bash

curl -k -b cookies.txt https://<host>/api/users | jq -r '.[] | select(.username=="craig") | .id'

POST /api/users

Creates a local user with a password.

Headers: Content-Type: application/json

Body fields:

Field	Type	Notes
username	string	Must be unique and cannot be root
roleId	integer	Must reference an existing role
password	string	Must satisfy the system password policy

Body:

JSON

{
  "username": "craig",
  "roleId": 2,
  "password": "ExamplePassword123!"
}

Example using a session cookie:

Bash

curl -k -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"craig","roleId":2,"password":"ExamplePassword123!"}' \
  https://<host>/api/users

Example using a PAT:

Bash

curl -k \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"username":"craig","roleId":2,"password":"ExamplePassword123!"}' \
  https://<host>/api/users

Example response (200 OK):

JSON

{
  "username": "craig",
  "id": "7",
  "roleId": 2,
  "sshKeys": []
}

If jq is available, you can capture the new user ID:

Bash

USER_ID=$(curl -k -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"craig","roleId":2,"password":"ExamplePassword123!"}' \
  https://<host>/api/users | jq -r '.id')

POST /api/users/userId/sshKey

Adds an SSH public key to an existing user.

Headers: Content-Type: application/json

Body fields:

Field	Type	Notes
sshKeyName	string	Friendly label for the key
sshKey	string	Full public key line, such as ssh-rsa ...

Body:

JSON

{
  "sshKeyName": "craig-laptop",
  "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."
}

Example using a session cookie:

Bash

curl -k -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"sshKeyName":"craig-laptop","sshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."}' \
  https://<host>/api/users/7/sshKey

Example using a PAT:

Bash

curl -k \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sshKeyName":"craig-laptop","sshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."}' \
  https://<host>/api/users/7/sshKey

Example response (200 OK):

JSON

{
  "sshKeyName": "craig-laptop",
  "sshKeyFingerprint": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
  "userId": "7"
}

End-to-End Example

Log in, list users, create a user, and then add an SSH key:

Bash

curl -k -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"ExamplePassword123!"}' \
  https://<host>/api/login

curl -k -b cookies.txt https://<host>/api/users

USER_ID=$(curl -k -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"craig","roleId":2,"password":"ExamplePassword123!"}' \
  https://<host>/api/users | jq -r '.id')

curl -k -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"sshKeyName":"craig-laptop","sshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."}' \
  https://<host>/api/users/$USER_ID/sshKey

Create a PAT and use it for the same workflow:

Bash

TOKEN=$(curl -k -b cookies.txt \
  -X POST \
  https://<host>/api/users/7/token | jq -r '.accessToken')

curl -k \
  -H "Authorization: Bearer ${TOKEN}" \
  https://<host>/api/users

curl -k \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"sshKeyName":"craig-laptop","sshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."}' \
  https://<host>/api/users/7/sshKey

Error Codes

Status	Meaning
401 Unauthorized	Authentication failed or session is missing.
403 Forbidden	User lacks the required permission.
404 Not Found	Incorrect endpoint path.
422 Unprocessable Entity	Missing fields, invalid role, duplicate username, or password policy failure.
500 Internal Server Error	Unexpected backend failure.