Create or update a credential

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

Request parameters

Body

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.

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.

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

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

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

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

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.