How to Deploy Apple Device Enrollment Program (DEP) Tokens via API in macOS MDM

In enterprise macOS environments, zero-touch deployment relies entirely on the successful synchronisation between Apple Business Manager (ABM) and your Mobile Device Management (MDM) solution. This synchronisation is cryptographically secured using Device Enrollment Program (DEP) Tokens (now officially part of Automated Device Enrollment).

While many administrators upload these tokens manually via their MDM’s web dashboard, highly automated environments—such as managed service providers (MSPs) or global enterprises with multiple MDM tenants—require programmatic deployment. This tutorial explains how to securely handle, encrypt, and deploy DEP tokens to an MDM server via API.

Understanding the DEP Token Architecture

A DEP token is not a simple static API key. It is an encrypted payload containing a certificate chain and an OAuth token used to authenticate requests to Apple’s Device Enrollment services.

The token exchange process involves three cryptographic components:

1. Public Key (PEM): Generated by your MDM server.
2. MDM Server Token (.p7m): Downloaded from Apple Business Manager, encrypted against your MDM’s Public Key.
3. Decrypted Token (JSON): The actual OAuth token payload extracted by the MDM after decrypting the `.p7m` file with its Private Key.

When automating this, you cannot simply push the `.p7m` file to an API endpoint unless the MDM explicitly supports server-side decryption. Often, the automation middleware must handle the decryption before pushing the JSON token to the MDM API.

Step 1: Generating the MDM Keypair

Before Apple will issue a DEP token, you must provide a public key. If you are building a custom MDM connector or using an API-first MDM, generate a secure RSA 2048-bit keypair using OpenSSL.

# Generate the Private Key
openssl genrsa -out mdm-private.key 2048

# Extract the Public Key (to upload to Apple Business Manager)
openssl req -new -key mdm-private.key -out mdm-cert.csr
openssl x509 -req -days 365 -in mdm-cert.csr -signkey mdm-private.key -out mdm-public.pem

You must upload mdm-public.pem to Apple Business Manager when creating a new MDM server entry. Apple will then provide a downloaded token file, typically named smime.p7m.

Step 2: Decrypting the DEP Token (.p7m)

The smime.p7m file downloaded from Apple is encrypted via S/MIME using the public key you provided. Before your API can ingest the token, it must be decrypted using the private key generated in Step 1.

Use OpenSSL to decrypt the S/MIME payload:

openssl smime -decrypt \
    -in smime.p7m \
    -inform DER \
    -inkey mdm-private.key \
    -out decrypted-token.json

If you inspect decrypted-token.json, you will see a structured JSON object containing the `consumer_key`, `consumer_secret`, `access_token`, and `access_secret`. This is the OAuth payload required to communicate with Apple’s API.

Step 3: Formatting the Token for MDM API Ingestion

Depending on your MDM vendor (e.g., Jamf Pro, Kandji, or Workspace ONE), the API endpoint will require the token to be formatted in a specific way. Most REST APIs require the decrypted JSON object to be Base64-encoded or passed as a nested JSON object within a POST request.

For example, if you are using an internal Python automation script to format the payload:

import json
import base64

# Read the decrypted token
with open('decrypted-token.json', 'r') as file:
    token_data = json.load(file)

# Encode to Base64 (if required by your MDM API)
token_string = json.dumps(token_data)
encoded_token = base64.b64encode(token_string.encode('utf-8')).decode('utf-8')

# Construct the API payload
payload = {
    "server_name": "Enterprise_MDM_Prod",
    "dep_token": encoded_token
}

Step 4: Pushing the Token via API

With the payload constructed, you can deploy the token to your MDM environment programmatically. Below is an example using `curl` to push the token to a generic MDM REST API endpoint.

curl -X POST "https://mdm.yourcompany.com/api/v1/dep/tokens" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "server_name": "Enterprise_MDM_Prod",
           "dep_token": "BASE64_ENCODED_TOKEN_STRING"
         }'

A successful response will typically return a `201 Created` or `200 OK` status, confirming that the MDM has ingested the token and initiated a synchronisation with Apple Business Manager.

Step 5: Verifying the Synchronisation State

Deploying the token is only the first half of the process; you must ensure the MDM has successfully authenticated with Apple. You can verify this by querying the MDM API for the DEP sync status.

curl -X GET "https://mdm.yourcompany.com/api/v1/dep/sync-status" \
     -H "Authorization: Bearer YOUR_API_KEY"

Look for a sync_state of success and an updated last_sync_time. If the status returns an auth_error, it usually indicates that the token was decrypted incorrectly or that the OAuth credentials have been revoked in Apple Business Manager.

By automating the cryptographic decryption and API deployment of DEP tokens, enterprise IT teams can eliminate manual dashboard uploads, streamlining the provisioning of zero-touch macOS deployment environments across global infrastructure.