Create Key

Before you begin

Before attempting to create a key, make sure you have access to create a key.

Request Structure


Endpoint:	`/ssh/key/create`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/key/create?gwsource=external` To understand the elements of the sample URL, click here.
Headers:
Content-Type:	application/json

Table 1. Request Parameters
Name	Description
sessionId `Header`	(Mandatory) Session ID received after login. Type: String Constraints: Required if username and password are not provided.
username `Header`	(Mandatory) AppViewX login username. Type: String Constraints: Required if sessionId is not provided.
password `Header`	(Mandatory) AppViewX login password. Type: String Constraints: Required if sessionId is not provided.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraints: The value of the param should be ‘application/json’.
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
requestId `queryParam`	(Mandatory) Request Id of the bulk upload request. Type: String
Payload `Body`	(Mandatory) Contains all the parameters to be sent in the request body for the post request. Type: Payload

Payload


Name	Description
keyGroup	(Mandatory) Name of the key group. Type: String
keyGroupId	(Mandatory) ID for the key group. Type: String
keyName	(Optional) Name of the SSH key. Type: String
keyType	(Mandatory) Type of key. Possible values: USER_KEY, HOST_KEY Type: String
algorithm	(Mandatory) Encryption algorithm used by the key. Type: String
bitLength	(Mandatory) Bit length of the key. Type: String
comment	(Optional) Comment or description for the key. Type: String
tags	Additional tags or metadata associated with the key (Example: “tags”:{“keyId”:”value”}) Type: Object

Response Structure

200 OK returns string of type application/json with the following body params.

Table 2. Response Parameters
Name	Description
response	Contains the response message of the api which will have a message and Fingerprint of the key. Type: createKeyResponse
message	null Type: String
appStatusCode	null. Type: String
tags	More info in case of failure response.

Table 3. createKeyResponse
Name	Description
fingerprint	Finger print of the created key. Type: String
message	Key Created Successfully Type: String

Status Codes

Table 4. Status Codes and Description
HTTP Status code	appStatusCode	Message and Possible remediation
200 OK	NA	Success
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials Possible remediation: Ensure that valid username and password or valid sessionId is provided as the header param.
400 Bad Request	VALIDATION_ERROR_0004	Mandatory field <<field name>> is missing or or empty Possible remediation: Check and ensure that valid value is provided for <<field name>> field in the request.
417 Expectation Failed	ERR-SSH-NB-305	Key name already exists Possible remediation: Check and ensure that a key with a given key name is not present. Else please change keyName and try again.
417 Expectation Failed	ERR-SSH_NB-262	Tag already exists with the given Key Invalid Key Algorithm or Bit Length Possible remediation: Check and ensure that the algorithm and bit length is present in the configured policy.
417 Expectation Failed	SSH-TAG-006	Tag ID is not valid Possible remediation: Check and ensure that the proper keyId is provided in tags.
417 Expectation Failed	SSH-TAG-006	Unable to create SSH key Possible remediation: Failed creating key via ssh-keygen command.
417 Expectation Failed	ERR-SSH-NB-302	Error while getting groups with read-write permission Possible remediation: Check and ensure that a user has RW access to the given key group.
417 Expectation Failed	ERR-SSH-NB-303	User does not have read-write access to the selected group Possible remediation: Check and ensure that a user has RW access to the given key group.

Sample Request/Response

Use Case

To create a key using /key/create API.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/key/create?gwsource=external

Sample Request


{
    "keyGroup": "Default_Key_Group",
    "keyGroupId": "5767bcef3465bfbf73e44727",
    "keyName": "samTest",
    "keyType": "USER_KEY",
    "algorithm": "ECDSA",
    "bitLength": "256",
    "comment": "",
    "tags": {
        "keyId1":"value",
        "keyId2":"value"
    }
}

Sample Response


{
    "response": {
        "message": "Key Created Successfully",
        "fingerprint": "zS022Xmd2J2Ouh8BHb5M8hbPYyxzBvN3ygXtr2f3IRY"
    },
    "message": null,
    "appStatusCode": null,
    "tags": {},
    "headers": null
}

Reference

Understanding the sample URL:

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Note: GWPORT is not required for SaaS setups.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: /ssh/host/create
gwsource: Source or origin of a gateway, for example: external.