This topic describes how to verify the validity of credentials by using the API.
Note
The verification does not store the credentials. It is only used to test whether the SSH connection is successful.
Call the API
If a password is set, you must pass the authentication. For more information, see API hybrid encryption.
Request path
POST /api/v1/security/credential/validate
Request parameters
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| target_type | string | Yes | HOST | The type of the target. Only "HOST" is supported. |
| ssh_credential_property | SshCredentialProperty | Yes | - | The properties of the SSH credential. For more information, see the Data structure of SshCredentialProperty section below. |
Data structure of SshCredentialProperty:
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| targets | []Target | Yes | [{"ip": "10.10.10.1", "port": 22}] | The list of target hosts. Each Target contains the ip and port. If the port is not specified, the default port is 22. The list cannot be empty and must contain at least one target. |
| username | string | Yes | root | The username for the SSH connection. |
| type | string | Yes | PASSWORD | The authentication type. Only "PASSWORD" is supported. |
| passphrase | string | Yes | *********** | The password for the SSH connection in plain text (which will be encrypted before storage). The value can be empty. |
Response
Parameter |
Type |
Description |
|---|---|---|
| successful | bool | Indicates whether the request is successful. |
| timestamp | time.Time | The timestamp when the server completed the request. |
| duration | int | The time taken by the server to process the request, in milliseconds. |
| status | int | The HTTP status code. |
| traceId | string | The trace ID of the request. |
| data | ValidationResult | The verification result. For more information, see the Data structure of ValidationResult section below. |
| error | ApiError | The error information of the request. The information includes the following items:
|
Data structure of ValidationResult:
Parameter |
Type |
Description |
|---|---|---|
| target_type | string | The type of the target, for example, "HOST". |
| succeeded_count | int | The number of targets that are verified successfully. |
| failed_count | int | The number of targets that are verified failed. |
| details | []ValidationDetail | The verification details. Each target has one detail. For more information, see the Data structure of ValidationDetail section below. |
Data structure of ValidationDetail:
Parameter |
Type |
Description |
|---|---|---|
| target | Target | The information of the target, including the ip and port. For more information, see the Data structure of Target section below. |
| connection_result | string | The connection result, for example, "SUCCESS" or "CONNECT_FAILED". This parameter is used for extension. |
| message | string | The error message. This parameter is empty if the verification is successful. |
Data structure of Target:
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| ip | string | Yes | 10.10.10.1 | The IP address. |
| port | int | No | 22 | The port number. If the port is not specified, the default port is 22. |
Examples
Request example
POST 10.10.10.1:2886/api/v1/security/credential/validate
{
"target_type": "HOST",
"ssh_credential_property": {
"targets": [
{
"ip": "10.10.10.1",
"port": 22
}
],
"username": "root",
"type": "PASSWORD",
"passphrase": "***********"
}
}
Response example
{
"successful": true,
"timestamp": "2025-10-14T15:19:01.277047628+08:00",
"duration": 1500,
"status": 200,
"traceId": "e6f64ba7f54e7a53",
"data": {
"target_type": "HOST",
"succeeded_count": 1,
"failed_count": 0,
"details": [
{
"target": {
"ip": "10.10.10.1",
"port": 22
},
"connection_result": "SUCCESS",
"message": ""
}
]
}
}