Skip to content

Upload external user cert

POST/smime/users/external/certificate

Email Management API · SMIME

Upload certificate file for external user and enable S/MIME for the user.

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

certificatestringrequired
The certificate must be in PEM format (base64 encoded content with header and footer lines).
Must be 300–32000 characters long.
confirmVerificationOnlyCertboolean
If the certificate being uploaded has a DSA/EC key, it can be used for signing/verification only, not for encryption/decryption. In such a case, the user needs to confirm they are aware of it and such upload is intentional.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external/certificate" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"certificate\": \"string\",
  \"confirmVerificationOnlyCert\": true
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external/certificate",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={'certificate': 'string', 'confirmVerificationOnlyCert': True},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "certificate": "string",
  "confirmVerificationOnlyCert": true
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external/certificate" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external/certificate", strings.NewReader(`{
  "certificate": "string",
  "confirmVerificationOnlyCert": true
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/email/v1/smime/users/external/certificate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "certificate": "string",
  "confirmVerificationOnlyCert": true
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Certificate uploaded successfully.

Response fields

itemsarray of objectrequired
List of external users with certificate information.
External user with associated certificate information.
Show child attributesHide child attributes
emailstring (email)required
Email address of the user.
Must be 3–255 characters long.
associatedCertificatesInfoarray of objectrequired
List of certificates associated with the user.
Information about certificates associated with a user.
Show child attributesHide child attributes
fingerprintstringrequired
SHA-256 fingerprint of the certificate.
Must match the pattern ^[a-fA-F0-9]{64}$. Must be exactly 64 characters long.
certificateDetailsobjectrequired
Detailed information about a certificate.
Show child attributesHide child attributes
issuerstringrequired
Certificate issuer distinguished name.
Must be at most 255 characters long.
validFromstring (date-time)required
Certificate validity start date.
expiresAtstring (date-time)required
Certificate validity end date.
originstringrequired
Indicates how the certificate was obtained.
Must be one of: created, uploaded, extracted, unknown.

Errors

Status Meaning
400 Invalid request.
401 Authentication required.
403 Authorization required.
409 Certificate already exists.
422 User already exists with two associated certificates.
500 Internal server error.
503 Server Unavailable.

All error responses share the same shape — see the error response object.

Response examples

201

{
  "items": [
    {
      "email": "john.doe@sophos.com",
      "associatedCertificatesInfo": [
        {
          "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "certificateDetails": {
            "issuer": "C=UK,O=Sophos Limited,CN=Sophos Root CA",
            "validFrom": "2024-12-31T14:25:09Z",
            "expiresAt": "2029-12-31T18:30:12Z",
            "origin": "created"
          }
        }
      ]
    }
  ]
}

See the guide for a narrative walkthrough of this API.