Create or update an SSH key
  • 4 minutes to read
  • Dark
    Light
  • PDF

Create or update an SSH key

  • Dark
    Light
  • PDF

Article summary

This document presents how to create or update an SSH key in PAM Core via API, the available endpoints, the parameters needed, example requests, and expected responses on success or in case of errors.

Authorization

To get started, make sure PAM Core is listed under Authorized resources in your A2A module. For more information on authorization, access the How to create an authorization for an application document.

Authentication

Each request in the API must have the OAuth Consumer Key and the OAuth Token of the client. For more information on authentication, access the How to authenticate an application document.

Methods

Create or update an SSH key

Request

To create an SSH key in PAM Core, send a request to the following endpoint:

POST /iso/pam/key

Alert!

If you're using A2A to create or update an SSH key and the corresponding device doesn't exist, you’ll need to create the device first. For more information, access the documentation on Configuring a device.

Request parameters

Body

Info

When sending an update request, it's not necessary to include parameters you don't want to update.

FieldTypeRequiredDescriptionExampleDefault Value
usernameStringNo. Note: Although not required, as a best practice, filling in this field makes it easier to search for the SSH key.Username related to the key on the device.jsilvausr
hostnameStringYes (when creating an SSH key.Name of the main device associated with the SSH key.API-Testing-
ipStringYes (when creating an SSH key).IP address of the main device associated with the SSH key.128.0.0.1-
public_keyStringYes (when creating an SSH key).Public key.public-key-
enabledBooleanNoSSH key status.true
private_keyStringYes (when creating an SSH key).Private key.private-key-
identifierStringYes (when updating an SSH key). Note: this field is essential for API updates. If it isn't provided during the creation of the SSH key, no changes to the key's fields can be made via the API update route. In this scenario, it will only be possible to activate or deactivate the key using the endpoints designated for these actions.SSH key identifier.api-ssgr1144-caracteres-tags-
key_nameStringNo. Note: Although not required, as a best practice, filling in this field makes it easier to search for the SSH key.Key name.api-ssgr1144-tags-
passwordStringNoOptional password that provides an additional layer of security to the private key, making it necessary to unlock the key before use.-
tagsStringNoSSH key tags.tag1,tag2,tag3,!@#$%¨*&()_+-
devicesArray of devicesNoDevices associated with the SSH key, containing its hostname.View example below*.-
hostnameStringNoHostname associated with the device.View example below*

*Example of a device array:

 "devices": [
        {
            "hostname": "API-Device1"
        },
        {
            "hostname": "API-Device2"
        },
        {
            "hostname": "API-Device3"
        },
        {
            "hostname": "API-Device4"
        }
    ]
}
Alert!
  • If you leave the devices field empty while creating an SSH key, the key won’t have any additional associated devices.
  • If you enter the value false in the enabled field, the SSH key will be created as inactive. To access this key's information, you must activate it manually by following the appropriate route or procedure within senhasegura.

Example request

{
    "username": "jsilva",
    "hostname" : "API-Testing",
    "ip": "128.0.0.1",
    "public_key": "public-key",
    "enabled": true,
    "private_key": "private-key",
    "identifier": "api-ssgr1144-caracteres-tags",
    "key_name": "api-ssgr1144-tags",
    "tags": "tag1,tag2,tag3,!@#$%¨&*()_+",
    "devices": [
        {
            "hostname": "API-Device1"
        },
        {
            "hostname": "API-Device2"
        },
        {
            "hostname": "API-Device3"
        },
        {
            "hostname": "API-Device4"
        }
    ]
}

Return

Creates or updates an SSH key in PAM Core, and returns a message informing about the process.

Expected response - create an SSH key

HTTP/1.1 200 OK

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Key successfully registered!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Key successfully registered!",
        "erro": false,
        "cod_erro": 0
    },
    "key": {
        "id": "14704",
        "tag": "api-ssgr1144-caracteres-tags2",
        "devices": [
            {
                "hostname": "API-Device1",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device2",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device3",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device4",
                "ip": "128.0.0.1"
            }
        ],
        "devices_error": []
    }
}

Expected response - update an SSH key

HTTP/1.1 201 Updated
{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Key updated successfully!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Key updated successfully!",
        "erro": false,
        "cod_erro": 0
    },
    "key": {
        "id": "14704",
        "tag": "api-ssgr1144-caracteres-tags2",
        "devices": [
            {
                "hostname": "API-Device1",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device2",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device3",
                "ip": "128.0.0.1"
            },
            {
                "hostname": "API-Device4",
                "ip": "128.0.0.1"
            }
        ],
        "devices_error": []
    }
}

In case of error - missing a required parameter

HTTP/1.1 400 Bad Request

{
	"code": 400,
	"response": {
	"status": 400,
	"message": "1004: The device's hostname was not informed",
	"error": true,
	"error_code": 1,
	"detail": "",
	"message": "1004: The device's hostname was not informed",
	"error": true,
	"cod_erro": 1
},
	"exception": {
	"code": 1004,
	"message": "1004: The device's hostname was not informed",
	"detail": ""
	}
}

Was this article helpful?