Set up Apple ADE verification

This guide walks an Apple Business (formerly Apple Business Manager/ABM) Administrator through the one-time setup required to enable Apple Business API integration for Automated Device Enrollment (ADE) verification in Firstbase. Setup has three parts: creating a least-privilege API role in Apple Business, creating an API account and generating credentials, and submitting those credentials to Firstbase.

Step 1: Create the API Role in Apple Business

You will create a custom role that grants Firstbase read-only access to verify ADE (Automated Device Enrollment, formerly DEP) status. Only one permission is needed.

1. Sign in to Apple Business at business.apple.com using an account with the Organization Administrator role.
2. In the top-right corner, click your organization name to open the menu, then click Settings.
3. In the Settings sidebar, under the Settings section, click Roles & Permissions. (Do not confuse this with Access Management further down the sidebar, which manages sign-in methods for human users.)
4. Create a new custom role with the following details:
   • Role name: Firstbase Verification
   • Description: Read-only role for Firstbase Verification. Used to query enrollment status only.
5. In the role editor, open the Devices tab.
6. Under Device Management, enable exactly one permission: "View device management services and add devices with Apple Configurator." Every other permission in Device Management must remain unchecked.
7. Leave all permissions under Organization, People, Apps & Services, and Brands unchecked.
8. Save the role.

For Apple's official instructions on creating a new API role, see:

Create an API account in Apple Business — Apple Support

Step 2: Create the API Account and Generate Credentials

The API account is the service identity Firstbase uses to query Apple Business. It is not a regular user account — it does not consume a Managed Apple ID and cannot sign into the Apple Business web UI.

1. Still in Settings, navigate to the Integrations section in the sidebar and click API.
2. Select Add API Account and provide the following details:
   • Account name: Firstbase Verification
   • Description: Read-only API account used by Firstbase to verify ADE (Automated Device Enrollment) status.
3. When prompted to assign a role, select the Firstbase role you created in Step 1. Do not select Administrator or any other built-in role.
4. Select Generate & Download to generate and download the private key. The file is a .pem file and is shown only once.
5. Before navigating away, note down or copy the following values — you will need all three in Step 3:
   • Key ID — a public identifier for the API key.
   • Client ID — the API account identifier. In Apple Business this value may be labeled Issuer ID; in Firstbase the field is labeled Client ID.
   • Private Key — the .pem file you downloaded.

Treat the .pem file like a password. Do not email it, paste it into chat or ticket systems, or commit it to source control. Only share it with Firstbase through the secure submission step below.

Step 3: Submit Credentials to Firstbase

Once you have the Key ID, Client ID, and .pem file, submit them to Firstbase through the Firstbase platform.

1. Sign in to the Firstbase platform.
2. Navigate to API & Integrations → Integrations. On the Available tab (or Active, if already connected), find Apple Business API under Device Management and click Configure (or Edit).
3. Enter your Key ID and Client ID in the respective fields (use the Client ID value from Apple Business, even if Apple labeled it Issuer ID).
4. For the private key, you have two options:
   • Upload the file: Use the file upload button to select your downloaded .pem file directly.
   • Paste the contents: Open the .pem file in a text editor, copy the entire contents, and paste into the PEM field.
5. Click Submit.

Firstbase stores your credentials securely. Your private key (.pem file) is encrypted at rest. Once submitted, your credentials are masked in the UI. You can update them later by re-entering new values, but the existing values cannot be re-displayed. Firstbase uses the credentials only to query Apple Business for ADE enrollment status and never to add, modify, or remove devices.

Troubleshooting connection issues

If ADE verification is not working after you connect Apple Business API, check whether the Key ID, Client ID, or private key was entered incorrectly.

When you click Submit, Firstbase stores your credentials and checks them against Apple Business in the background. If any value is wrong, incomplete, or does not belong to the API account you created in Steps 1 and 2, verification will not work even though your credentials appear on file in Firstbase.

Update and resubmit your credentials

1. Sign in to the Firstbase platform as an Admin.
2. Go to API & Integrations → Integrations → Device Management → Apple Business API, then click Edit.
3. Re-enter the values that need to be corrected. To replace a stored value, enter the new value in that field. Do not leave a field blank unless you intend to keep the current stored value.
4. Click Submit again.

Before you resubmit, confirm in Apple Business

• The API account still exists under Settings → Integrations → API.
• The account is assigned to the Firstbase Verification role from Step 1 (not Administrator or another built-in role).
• The Key ID and Client ID are from the same API account.
• The Client ID matches what Apple shows (Apple may label this Issuer ID).
• The .pem file is complete, including the BEGIN and END lines, and was not truncated or altered when copied.

If you no longer have the original private key, Apple Business cannot show it again. Create a new API account (or delete and recreate the existing one), generate a new key, and submit the new credentials to Firstbase.

If verification still does not work after resubmitting corrected credentials, contact your Customer Success Manager (CSM) or reach out via your normal Firstbase support channel.

Rotating or Revoking Credentials

• To revoke access: Delete the API account in Apple Business (Settings > Integrations > API). This immediately prevents Firstbase from querying Apple Business.
• To rotate credentials: Create a new API account in Apple Business using the same Firstbase role, generate new credentials, submit the new credentials to Firstbase, then delete the previous API account.

Firstbase recommends rotating credentials annually, or whenever an administrator with access to the original .pem file leaves your organization.

How We Protect Your Data

Apple Business controls the device deployment chain for your fleet, so the credentials Firstbase holds on your behalf are sensitive. Verification is designed with the following safeguards:

• Read-only access. The Firstbase role grants only the "View device management services and add devices with Apple Configurator" permission. The service cannot release, retire, reassign, or otherwise modify any device in your Apple Business organization.
• Least-privilege role. The role you create has exactly one permission enabled. Every other device-management permission is disabled.
• Encrypted credentials at rest. Your private key (.pem file) is encrypted at rest. Your Key ID and Client ID are stored securely, decrypted only in memory when a query runs, and are never written to application logs or displayed in full in the dashboard after submission.
• No write-back to Apple Business. The audit service never creates, modifies, or deletes records in your Apple Business organization. All remediation actions are performed by you or by Firstbase Operations directly in Apple Business.
• Internal-only tool. Verification is an internal Firstbase Operations tool. Access is restricted to authorized Firstbase staff via SSO with role-based permissions. Your stored credentials are never displayed in the UI, even to Firstbase staff.
• Audit trail. Every audit run is logged with a timestamp and the operator (or "system" for automated runs), supporting operational accountability and incident review.
• Encrypted infrastructure. The service runs on managed cloud infrastructure with encryption in transit (TLS) and at rest. Secrets are stored in an encrypted configuration store, not in source code.

Need Further Assistance?

If you have questions about the setup process, contact your Customer Success Manager (CSM) or Operations Success Manager (OSM). For technical issues with Apple Business enrollment or to request an on-demand audit, reach out via your normal Firstbase support channel.