Deploy enterprise certificates to devices — Esper API command

Android

When you need to install enterprise certificates (such as VPN CA or client certificates) on managed Android devices, the Esper Console does not provide a general-purpose certificate installation workflow. Certificate deployment is handled through the Esper Device Command API using the INSTALL_CERTIFICATE command.

Why this happens

Android's certificate trust store requires certificates to be installed at the device level through a privileged system call. Esper exposes this through the Device Command API rather than the Console UI, because certificate payloads require Base64 encoding and per-device or per-group targeting that the API handles more precisely than a UI workflow.

Before you begin

Collect the following before starting:

Your certificate file (.p12, .pfx, or .pem)
Your Esper tenant name (visible in your Console URL, e.g. acme from acme.esper.cloud)
Your Esper API bearer token (found in Esper Console → API Key Management)
The device ID(s) or group ID(s) where the certificate should be installed

Steps

Convert your certificate to Base64. The API requires the certificate as a single-line Base64-encoded string. Run the appropriate 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 on Linux/macOS suppresses line breaks. The API will reject a Base64 string that contains newlines.
Identify your API endpoint. Your tenant-specific endpoint follows this pattern:
```
https://{tenant-name}-api.esper.cloud/api/v0/command/
```
Replace {tenant-name} with your Esper tenant name. For example, if your Console URL is acme.esper.cloud, your endpoint is https://acme-api.esper.cloud/api/v0/command/.
Submit the INSTALL_CERTIFICATE command. Send a POST request to your API endpoint. Replace <BASE64_ENCODED_CERTIFICATE_STRING> with the full 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 bearer token in the request header:
```
Authorization: Bearer <your-api-token>
```
Target the command to specific devices or groups. Add one of the following targeting parameters to your request body. Sending the command without a target will result in an error:
- device_ids — an array of individual device IDs
- group_ids — an array of group IDs
Refer to the Esper API reference for the full request schema and additional targeting options.
Check the command result in the Esper Console. Navigate to Devices & Groups → [Device Name] → Activity Feed and confirm the INSTALL_CERTIFICATE command shows a status of Success. A status of Failure or Timed Out means the certificate was not installed — see troubleshooting below.
Confirm the certificate is present on the device. On the target device, open Settings → Security → Trusted Credentials → User (the exact path may vary by manufacturer and Android version) and verify the certificate appears in the list.

Verify: The Activity Feed entry for the command should show Success within a few minutes of submission. The certificate should appear under Trusted Credentials on the device, and any VPN or TLS connection that depends on the certificate should connect without a trust error.

Troubleshooting

Command fails immediately: Confirm the Base64 string contains no newlines or spaces. Re-run the Base64 conversion command and copy the full output directly from cert_base64.txt without reformatting.
Command succeeds but certificate does not appear in Trusted Credentials: Confirm cert_file_type matches the actual certificate format. A .p12 file submitted with cert_file_type: pem will silently fail to install.
API returns a 401 or 403 error: Your bearer token may be expired or scoped incorrectly. Generate a new token in Esper Console → API Key Management and retry.
Device is offline: The command will be queued and delivered when the device reconnects. Check the Activity Feed for a Queued status and allow time for the device to come online.

If this doesn't resolve it

If the certificate command continues to fail after following these steps, contact Esper Support with the following information:

The full API request body (with the Base64 certificate string redacted)
The complete API response, including HTTP status code and error message
The device ID and the Activity Feed entry for the failed command
The certificate type (.p12, .pfx, or .pem) and the issuing CA

Still need help?

If you're unable to deploy certificates to your devices using the Esper API command, please submit a support ticket and include the certificate file format, the API request payload you're using, and any error messages returned.