Create or update a credential
  • 11 minutes to read
  • Dark
    Light
  • PDF

Create or update a credential

  • Dark
    Light
  • PDF

Article summary

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

Methods

POST Create or update a credential

Request

To create or update a credential in PAM Core, send a request to the following endpoint:

/iso/pam/credential

Alert!

If you're using A2A to create or update a credential and the corresponding device doesn't exist, you’ll need to create the device first. For more information, access the document on configuring a device.

Request parameters

Body

FieldTypeRequiredDescriptionExampleNew Credential Default Value
identifierStringNo (when creating a credential). Yes (when updating a credential). Note: go to the Credential management options section for more details.Unique string defined by the user to identify the credential.123-
usernameStringYesUsername assigned to the credential.my_userusr
contentStringNoPassword assigned to the credential.MyPrettyPassword@1234-
additionalStringNoAdditional information.DATABASE-
tagsStringNoTags associated with the credential.api, app-
credential_typeStringNoType of credential. A new type is created for each unique value.Domain UserLocal User
domainStringNoDomain name or abbreviation. Only previously registered domains are accepted.senhasegura.lab-
parent_passwordIntNoID of the parent credential.123-
hostnameStringYesDevice name.localhost-
ipStringYesDevice's IP address.127.0.0.1-
typeStringNoDevice type. A new type is created for each unique value.Server-
vendorStringNoDevice vendor. A new vendor is created for each unique value.Debian-
modelStringNoDevice model. A new model is created for each unique value.10.0 Buster-
siteStringNoDevice's site. A new site is created for each unique value.Default-
device_domainStringNoDomain name or abbreviation. Only previously registered domains are accepted.senhasegura.lab-
device_tagsStringNoTags associated with the device.api, app-
connectivitiesStringNoDevice connectivity.SSH:22, HTTPS:443-
session_remote_configStringNoLogin expression.SSH:EXPECT:FILL-

Credential management options

After sending the request, you can either create or update a credential registered in PAM Core by choosing between filling in the identifier parameter or the hostname, ip, and username parameters.

Info

Before you proceed, know that when the terms valid and invalid are used, they mean:

  • valid - a value that has been previously assigned to a credential.
  • invalid - a value that hasn't been previously assigned to a credential.

Fill in the identifier parameter

When providing an identifier, pay attention to the following:

  • The identifier parameter takes precedence over the credential’s username. Therefore, providing an identifier when creating the credential enables you to update the credential’s username in a subsequent call.
  • Provide a valid hostname and ip.
  • When updating the credential, if the identifier provided is invalid, the system will search for the credential using its hostname, ip, and username information.
  • If the credential is found, it will be updated with all the provided parameters, including the identifier.
  • If the credential isn’t found, a new one will be created based on the parameters provided.

Create a credential with an invalid identifier

When you provide an invalid identifier, the system will search for the credential using its hostname, ip, and username. If these values aren’t found, the credential will be created.

Example request

{
    "username" : "jhoncredential",
    "hostname": "Linkedin",   
    "ip": "linkedin.com",
    "content": "vfdvds##@",
    "tags": "social",
    "identifier": "identifierjhon"
}


Return

Creates a credential in PAM Core, and returns a message with information about the creation process.

Expected response

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Credential successfully registered!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Credential successfully registered!",
        "erro": false,
        "cod_erro": 0
    },
    "credential": {
        "id": "115",
        "tag": null
    }
}

Update a credential with a valid identifier

When you provide a valid identifier, the credential will be updated based on the other parameters provided.

Example request

{
    "username" : "cred6updatetest",
    "hostname": "Linkedin",   
    "ip": "linkedin.com" ,
    "identifier": "identifiertesting",
    "content": "bfgbdfbdsd#@"
}

Return

Updates a credential in PAM Core based on its identifierand returns a message with information about the updating process.

Expected response

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Credential updated successfully!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Credential updated successfully!",
        "erro": false,
        "cod_erro": 0
    },
    "credential": {
        "id": "114",
        "tag": "identifierjhon"
    }
}

Update a credential with an invalid identifier

When you provide an invalididentifier, the system will search for the credential using its hostname, ip, and username information. If these values are found, the credential will be updated.

Example request

{
    "username" : "[email protected]",
    "hostname": "Outlook",
    "ip": "login.live.com" ,
    "identifier": "identifiertesting"
}

Return

Updates a credential in PAM Core based on its username, hostname and ip and returns a message with information about the updating process.

Expected response

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Credential updated successfully!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Credential updated successfully!",
        "erro": false,
        "cod_erro": 0
    },
    "credential": {
        "id": "1",
        "tag": "identifiertesting"
    }
}

In case of error - missing a required parameter

HTTP/1.1 400 Bad Request
{
    "response": {
        "status": 400,
        "mensagem": "1004: The device's hostname was not informed",
        "erro": true,
        "message": "1004: The device's hostname was not informed",
        "error": true
    },
    "exception": {
        "code": 1004,
        "message": "1004: The device's hostname was not informed",
        "detail": null
    }
}

Fill in the hostname, ip, and username parameters

  • When creating a credential, if you don’t provide an identifier, you must provide a hostname, an ip, and a username.
  • The hostname and ip must be valid.
  • If a valid username is provided, the credential will be updated.
  • If the username provided is invalid, a new credential will be created.
Info

If you assign a unique identifier to the credential during its creation, you can use it to edit the credential in a subsequent call.

Create a credential with an invalid username

When you provide an invalid username, a credential will be created based on the other parameters provided.

Example request

{
    "hostname": "gmail",
    "username": "cred9",
    "ip": "https://www.gmail.com",
    "identifier": "identifier2",
    "additional": "my credential"
}

Return

Creates a credential in PAM Core and returns a message with information about the creation process.

Expected response

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Credential successfully registered!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Credential successfully registered!",
        "erro": false,
        "cod_erro": 0
    },
    "credential": {
        "id": "115",
        "tag": null
    }
}

Update a credential with a valid username

When you provide a valid username, the credential will be updated based on the other parameters provided.

Example request

{
    "username" : "cred9",
    "hostname": "Facebook",   
    "ip": "facebook.com",
    "content": "updating-my-password",
    "tags": "face, social, updated"
}

Return

Updates a credential in PAM Core based on its username and returns a message with information about the updating process.

Expected response

{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Credential updated successfully!",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Credential updated successfully!",
        "erro": false,
        "cod_erro": 0
    },
    "credential": {
        "id": "115",
        "tag": null
    }
}

In case of error - missing a required parameter

HTTP/1.1 400 Bad Request
{
    "response": {
        "status": 400,
        "mensagem": "1004: The device's hostname was not informed",
        "erro": true,
        "message": "1004: The device's hostname was not informed",
        "error": true
    },
    "exception": {
        "code": 1004,
        "message": "1004: The device's hostname was not informed",
        "detail": null
    }
}

Other credential parameters

You can also configure the credential by adding other parameters available in the following tabs:

  • Execution settings.
  • Session settings.
  • Additional settings.
  • JIT settings.

Execution Settings

Request body parameters

FieldTypeRequiredDescriptionExampleNew Credential Default Value
parent_credentialStringNoParent credential selected for edited credential.my_user-
parent_hostnameIntNoHostname for the parent credential selected.gmail-
parent_ipIntNoIP of the device for the parent credential selected.10.10.10.10-
automatic_changeBooleanNoEnables or disables automatic change.truefalse
agent_based_password_changeBooleanNoEnables or disables agent-based password change.false
change_pluginStringNoChange plugin to be used when rotating the credential.SSH-
change_templateStringNoChange template for rotating the credential.3COM-
use_own_credential_to_connectBooleanNoEnables or disables the use of own credential to connect.falsefalse
authentication_credentialStringNoCredential used to authenticate during credential rotation process.cred2-
authentication_hostnameStringNoThe authentication hostname.gmail-
authentication_ipStringNoThe authentication IP address.https://www.gmail.com-
statusBooleanNoEnables or disables Credential reconciliation after rotation failure.truefalse
reconciliation_credentialStringNoCredential to be used in the reconciliation process.cred2-
reconciliation_hostnameStringNoThe reconciliation hostname.gmail-
reconciliation_ipStringNoThe reconciliation IP address.https://www.gmail.com-
reconciliation_pluginStringNoExecution plugin for the credential reconciliation process.SSH-
reconciliation_templateStringNoTemplate for the credential reconciliation process.3COM-

Example request

{
    "username": "exemplo caderno 3.32",
    "hostname": "API-Testing",
    "ip": "128.0.0.1",
    "execution_settings": 
    {
        "parent_credential": "cred2",
        "parent_hostname": "gmail",
        "parent_ip": "https://www.gmail.com",
        "automatic_change": true,
        "agent_based_password_change": true,
        "change_plugin": "SSH",
        "change_template": "3COM",
        "use_own_credential_to_connect": false,
        "authentication_credential": "cred2",
        "authentication_hostname": "gmail",
        "authentication_ip": "https://www.gmail.com",
        "status": true,
        "reconciliation_credential": "cred2",
        "reconciliation_hostname": "gmail",
        "reconciliation_ip": "https://www.gmail.com",
        "reconciliation_plugin": "SSH",
        "reconciliation_template": "3COM"
    }
}

Session settings

Request body parameters

FieldTypeRequiredDescriptionExampleNew Credential Default Value
SSHBooleanNoEnables or disables SSH protocol.truefalse
TelnetBooleanNoEnables or disables Telnet protocol.truefalse
MySQLBooleanNoEnables or disables MySQL.truefalse
SQL ServerBooleanNoEnables or disables SQL Server.truefalse
HTTPBooleanNoEnables or disables HTTP protocol.truefalse
HTTPSBooleanNoEnables or disables HTTPS protocol.truefalse
RDPBooleanNoEnables or disables RDP protocol.truefalse
X11 ForwardBooleanNoEnables or disables X11 Forward.truefalse
VNCBooleanNoEnables or disables VNC.truefalse
restrict_access_to_remote_applicationBooleanNoEnables or disables restricted access to remote application.truefalse
macrosArray of objectsNoAutomation macro for RemoteApp.--
remote_appStringNoRemoteApp automation associated to the credential.MySQL-
connectivityStringNoConnectivity for RemoteApp automation associated to the credential.SSH-
use_own_credential_to_connectBooleanNoEnables or disables the use of own credential to connect.falsetrue
authentication_credentialStringNoThe authentication credential.cred2-
authentication_hostnameStringNoThe authentication hostname.gmail-
authentication_ipStringNoThe authentication IP address.https://www.gmail.com-

Example request

{
    "username": "exemplo caderno 3.32",
    "hostname": "API-Testing",
    "ip": "128.0.0.1",
    "session_settings": 
        {
            "SSH": true,
            "Telnet": true,
            "MySQL": true,
            "SQL Server": true,
            "HTTP": true,
            "HTTPS": true,
            "RDP": true,
            "X11 Forward": true,
            "VNC": true,
            "restrict_access_to_remote_application": true,
            "macros": 
            [
                {
                    "remote_app": "MySQL",
                    "connectivity": "SSH"
                },
                {
                    "remote_app": "Kaspersky",
                    "connectivity": "RDP"
                }
            ],
            "use_own_credential_to_connect": false,
            "authentication_credential": "cred2",
            "authentication_hostname": "gmail",
            "authentication_ip": "https://www.gmail.com"
        }
}


Additional settings

Request body parameters

FieldTypeRequiredDescriptionExampleNew Credential Default Value
identifierStringNoUnique string to identify the credential.identifier-
user_credentia_ownerStringNoThe user credential owner.admin-
server_pathStringNoLocation path of the script or file where the credential is located./etc/host-
secret_keyStringNoThe secret key (TOTP).295B3LA1M6LRAHI2S7G1A36LMK6I4IWW-
criticalityStringNoThe criticality level. Possible values are Low, Medium, and High.HighMedium
additional_authentication_fieldsArray of objectsNoList of additional authentication fields.--
nameStringNoName of an additional authentication.name-
short_nameStringNoShort name of an additional authentication.short_name1-
valueStringNoThe value to be filled in during the additional authentication process.Enable-
notesStringNoGeneral notes about the credential.Credential to be used only in network A.-

Example request

{
    "username": "exemplo caderno 3.32",
    "hostname": "API-Testing",
    "ip": "128.0.0.1",
    "additional_settings": 
        {
            "identifier": "identifer",
            "user_credential_owner": "admin",
            "server_path": "/etc/host",
            "secret_key": "295B3LA1M6LRAHI2S7G1A36LMK6I4IWW",
            "criticality": "High",
            "additional_authentication_fields": 
            [
                {
                    "name": "name",
                    "short_name": "short_name1",
                    "value": "Enable"
                },
                {
                    "name": "name2",
                    "short_name": "short_name2",
                    "value": "value"
                }
            ],
            "notes": "Credential to be used only in network A"
        }
}

JIT Settings

Request body parameters

FieldTypeRequiredDescriptionExampleNew Credential Default Value
jitBooleanNoEnables or disables just in time (JIT) settings.falsefalse
credential_creation_and_deletionBooleanNoEnables or disables the creation and deletion of credentials.true-
enable_disable_credentialBooleanNoEnables or disables a credential.false-
use_own_credential_to_connectBooleanNoEnables or disables the use of own credential to connect.falseYes
authentication_credentialStringNoThe authentication credential.cred2-
authentication_hostnameStringNoThe authentication hostname.gmail-
authentication_ipStringNoThe authentication ip address.https://www.gmail.com-
credential_creation_pluginStringNoThe authentication credential plugin.Windows RM-
credential_creation_templateStringNoThe authentication credential template.Create credential Windows server.-
credential_deletion_pluginStringNoThe credential deletion plugin.Windows RM-
credential_deletion_templateStringNoThe credential deletion template.Delete credential Windows server.-
credential_enable_pluginStringNoThe credential enable plugin.Windows RM-
credential_enable_templateStringNoThe credential enable template.Enable credential Windows server.-
credential_disable_pluginStringNoThe credential disable plugin.Windows RM-
credential_disable_templateStringNoThe credential disable template.Disable credential Windows server.-

Example request


{
    "username": "exemplo caderno 3.32",
    "hostname": "API-Testing",
    "ip": "128.0.0.1",
    "jit_settings": 
        {
            "jit": false,
            "credential_creation_and_deletion": true,
            "enable_disable_credential": false,
            "use_own_credential_to_connect": false,
            "authentication_credential": "cred2",
            "authentication_hostname": "gmail",
            "authentication_ip": "https://www.gmail.com",
            "credential_creation_plugin": "Windows RM",
            "credential_creation_template": "Create credential Windows server",
            "credential_deletion_plugin": "Windows RM",
            "credential_deletion_template": "Delete credential Windows server",
            "credential_enable_plugin": "Windows RM",
            "credential_enable_template": "Enable credential Windows server",
            "credential_disable_plugin": "Windows RM",
            "credential_disable_template": "Disable credential Windows server"
        }
}

Possible errors

Here’s a list of HTTP error codes and their descriptions:

  • 1004: Missing device's hostname.
  • 1005: Missing device's ip address.
  • 1007: Credential not found.
  • 1009: No access to credential.

Was this article helpful?