This topic describes how to create credentials for connecting to the host where the nodes of the cluster are located by using an API. During credential creation, SSH verification is performed, and the password is encrypted and stored.
Callout
Interface constraints
If you set a password, you must pass authentication. For more information, see API hybrid encryption.
Request path
POST /api/v1/security/credential
Request parameters
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| target_type | string | Yes | HOST | The target type. Only "HOST" is supported. |
| name | string | Yes | my-credential | The name of the credential. |
| description | string | No | SSH credential for hosts | The description of the credential. |
| ssh_credential_property | SshCredentialProperty | Yes | - | The properties of the SSH credential. For more information, see Data structure of SshCredentialProperty 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 ip and port. For more information, see Data structure of Target below. |
| username | string | Yes | root | The username for SSH connection. |
| type | string | Yes | PASSWORD | The authentication type. Only "PASSWORD" is supported. |
| passphrase | string | Yes | *********** | The password for SSH connection (plaintext, which will be encrypted before storage). This parameter can be empty. |
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 not provided, the default value is 22. |
Response
Parameter |
Type |
Description |
|---|---|---|
| successful | bool | Indicates whether the request was 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 | Credential | The returned credential information. For more information, see Data structure of Credential below. |
| error | ApiError | The error information generated by the request, which contains the following parameters:
|
Data structure of Credential:
Parameter |
Type |
Description |
|---|---|---|
| credential_id | int64 | The ID of the credential. |
| name | string | The name of the credential. |
| target_type | string | The target type. |
| description | string | The description of the credential. |
| ssh_secret | SshSecret | The SSH key information (excluding the password). For more information, see Data structure of SshSecret below. |
| create_time | time.Time | The creation time. |
| update_time | time.Time | The update time. |
Data structure of SshSecret:
Parameter |
Type |
Description |
|---|---|---|
| targets | []Target | The list of target hosts. |
| username | string | The username. |
| type | string | The authentication type. |
Examples
Request example
POST 10.10.10.1:2886/api/v1/security/credential
{
"target_type": "HOST",
"name": "my-credential",
"description": "SSH credential for hosts",
"ssh_credential_property": {
"targets": [
{
"ip": "10.10.10.1",
"port": 22
}
],
"username": "root",
"type": "PASSWORD",
"passphrase": "********"
}
}
Response example
{
"successful": true,
"timestamp": "2025-10-14T15:14:01.277047628+08:00",
"duration": 36,
"status": 200,
"traceId": "e6f64ba7f54e7a47",
"data": {
"credential_id": 1,
"name": "my-credential",
"target_type": "HOST",
"description": "SSH credential for hosts",
"ssh_secret": {
"targets": [
{
"ip": "10.10.10.1",
"port": 22
}
],
"username": "root",
"type": "PASSWORD"
},
"create_time": "2025-10-14T15:14:01.277047628+08:00",
"update_time": "2025-10-14T15:14:01.277047628+08:00"
}
}