Installing certificates on Android via Esper API (INSTALL_CERTIFICATE command)

Android

You can install certificates on your Android managed devices using the Esper Device Command API. This is useful when you need to deploy enterprise certificates (such as VPN CA or client certificates) that must be trusted at the device level before a VPN connection can succeed.

Before you begin

Ensure you have the following information available:

Your certificate file (.p12,.pfx, or.pem)
Your Esper tenant name (used to construct your API endpoint)
Your Esper API bearer token
The device ID(s) or group ID(s) where you want to install the certificate

Note: Certificate deployment is only available through the Esper API. There is no certificate installation workflow in the Esper Console UI for general-purpose certificates outside of Wi-Fi profiles.

Step 1: Convert your certificate to Base64 format

The Esper API requires your certificate to be Base64-encoded. Choose the command for your operating system:

On Linux or macOS:

base64 -w 0 -i your_certificate.p12 -o cert_base64.txt

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\path\to\your_certificate.p12")) | Out-File cert_base64.txt

The -w 0 flag (Linux/macOS) prevents line breaks in the output, which is important for API submission.

Step 2: Identify your API endpoint

Your Esper API endpoint follows this pattern:

https://{tenant-name}-api.esper.cloud/api/v0/command/

Replace {tenant-name} with your Esper tenant name.

Step 3: Submit the INSTALL_CERTIFICATE command

Send a POST request to your API endpoint with the following payload. Replace cert_data_base64 with the full Base64 string from Step 1, and set cert_file_type to match your certificate format:

{
 "command_type": "DEVICE",
 "command": "INSTALL_CERTIFICATE",
 "command_args": {
 "cert_file_type": "pkcs12",
 "cert_data_base64": "<BASE64_ENCODED_CERTIFICATE_STRING>"
 }
}

Use these values for cert_file_type:

pkcs12 — for.p12 or.pfx files
pem — for.pem or.crt files

Include your API bearer token in the Authorization header (format: Bearer <your-api-token>).

Step 4: Target the command to your devices

Add targeting parameters to your request to specify which devices should receive the certificate. Include one of the following in your request body:

device_ids — a list of specific device IDs
group_ids — a list of specific group IDs

Refer to the Esper API documentation for the full specification of targeting options.

Step 5: Verify the certificate installation

To confirm the command executed successfully:

In the Esper Console, go to Devices & Groups → [Device Name] → Command History and check that the command status shows as completed.
On the target device, navigate to Settings → Security → Trusted Credentials → User (the exact path may vary by device manufacturer) and verify the certificate appears in the list.
Test the end-to-end VPN connection to validate that the certificate is being recognized.

Troubleshooting

The certificate does not appear in trusted credentials:

Verify that the cert_file_type value matches your actual certificate format. A mismatch (for example, specifying pem for a pkcs12 file) will cause a silent failure.
Check that your Base64 string contains no line breaks or extra whitespace. Use the -w 0 flag when encoding on Linux/macOS.

The VPN connection still fails after certificate installation:

The issue may be related to certificate chain trust (missing intermediate or root CA certificates), VPN client configuration, or device-level keystore restrictions. Review the VPN client logs on the device for more details.

The API returns a 400 or 422 error:

Ensure your Base64 string has no line breaks or whitespace. If using the base64 command on Linux or macOS, always include the -w 0 flag.

The command remains in Queued state and never executes:

Confirm that the target device is online.
Verify that the Esper Agent on the device is up to date.
If the device is online but the command still does not execute, contact Esper Support.

Important notes

Password-protected certificates: If your.p12 file is password-protected, refer to the Esper API documentation to confirm whether the INSTALL_CERTIFICATE command supports a cert_password parameter.
Credential store location: This method installs the certificate into the Android user credential store (or managed keystore on fully managed devices). The exact behavior and location may vary by device manufacturer, Android version, and OEM customization.
Wi-Fi certificates: If you are deploying certificates as part of a Blueprint Wi-Fi profile, use the Wi-Fi configuration path instead. This API command is for general-purpose certificates only.
Test before fleet deployment: Certificate installation behavior can vary across Android versions (10, 11, 12, 13+) and OEM skins. Test the certificate installation on a representative device before rolling out to your entire fleet.

Still need help?

If you encounter issues that this article does not address, submit a support ticket. Include the command payload, any error messages, and the device model and Android version.