Getting Started

Getting Started

The Home screen

When you open Magic Toolbox you see a grid of all 15 tools. Click a tool to open it.

The toolbar at the top of the window has these buttons:

Button	What it does
Home	Goes back to the tool grid. Only shown while a tool is open
Licence badge (Licensed / Trial – 41h 12m / Unlicensed)	Opens About, where you activate or deactivate your licence
Appearance	Cycles through following the system, Light and Dark
Debug Log	Opens the captured logs (see Preferences)
About (?)	Shows the version, licence details, and links to the website and GitHub
Close	Hides the window. The app keeps running in the menu bar

The menu bar icon

Magic Toolbox keeps a wand icon in the macOS menu bar. From there you can:

• open the main window, or go straight to any tool
• open Preferences… (also ⌘,)
• Quit Magic Toolbox (⌘Q)

Closing the window does not quit the app. Use Quit in the menu bar menu to quit it completely.

Only one copy of Magic Toolbox runs at a time. If you open it again, the window that's already running comes to the front.

---

Connecting to Jamf Pro

Most tools start with a Connect step. The form looks the same everywhere:

1. Jamf Pro Instance: your server address.
   • Typing just the tenant name, for example acme, fills in acme.jamfcloud.com.
   • https:// is added if you leave it out.
   • On-premises servers work too: enter the full URL, including the port if you use one, e.g. https://jamf.acme.com:8443.
   • If you enter an http:// address you'll see a warning, because credentials would be sent unencrypted. Only do this on an isolated private network.
2. Authentication, one of:
   • API Client (OAuth): a Client ID and Client Secret. Recommended.
   • Username & Password: a Jamf Pro user account.
3. Save credentials to Keychain (optional) fills in the form automatically the next time you open that tool. Once it's on, the form is saved as soon as it's complete. Clear Saved removes the saved entry. If you have Saved Servers, click one to fill in the form, or click Enter credentials manually… to show the fields.
4. Click Connect & Check Permissions.

Compare has its own connect form, with a Save to Keychain switch for each instance.

How Magic Toolbox signs in

• API Client (OAuth): the app requests an access token from /api/oauth/token with the client credentials grant.
• Username & Password: the app requests a token from /api/v1/auth/token with basic authentication.

The access token is kept in memory only and is never saved. When it expires, the app signs in again with the same credentials. Each request times out after 30 seconds.

The permission check

After you sign in, Magic Toolbox looks up what your account is allowed to do and lists each privilege the tool needs as Allowed or Denied:

• All permissions verified: click Continue →.
• Permission issues detected: you can fix the account in Jamf Pro (Settings → System → API Roles & Clients), or click Proceed Anyway →. Actions that need a missing privilege will fail, and the tool reports each failure.
• Back returns to the Connect step.

For the privilege checks to work, the account also needs to be able to read its own permissions. See Jamf API Permissions.

Creating an API client in Jamf Pro (recommended)

1. In Jamf Pro, go to Settings → System → API Roles and Clients.
2. API Roles → New: give it a name (e.g. Magic Toolbox – Read Only) and add the privileges from Jamf API Permissions.
3. API Clients → New: give it a name, assign the role, set a token lifetime, and enable the client.
4. Click Generate Client Secret, then copy the Client ID and Secret into Magic Toolbox.

Tip: make separate roles for different jobs, for example a read-only role for auditing and a role with write access for Clone and Wipe, so you only use write access when you mean to.

---

Saved Servers

If you work with several Jamf Pro servers, save them once and choose them from any tool.

1. On the Home screen, open Saved Servers → Manage Servers…

2. Click Add Server and fill in:
   • Display Name, e.g. Acme Production
   • Jamf Pro URL, e.g. company.jamfcloud.com
   • API Client (OAuth) or Username & Password details
3. Click Add Server.

From then on, the Connect step of each tool shows a Saved Servers list. Click a server to fill in the form, or choose Enter credentials manually… to type different details. When you click a saved server, the tool also remembers it for next time.

The display name, URL, authentication type, username and Client ID are kept in the app's preferences. The full credentials, including the password or client secret, are kept in the macOS Keychain. You can Edit a saved server in Manage Servers…, and tools pick up the change the next time you open them. The trash button deletes a server straight away, with no confirmation.

---

Common features

• Step bar: most tools show a step bar at the top (for example Connect → Options → Scan → Results) so you can see where you are.
• HTML reports: many tools can Export HTML. Reports are single, self-contained files that open in any browser. In Preferences you can set the accent colour (used by Compare and Wipe reports) and add your organisation's name and logo (used by Compare, Wipe, PPPC Analyser, Smart Group Audit and Unused reports).
• Drag and drop: tools that work on a local app or package (Inspector, PPPC Analyser, System Extensions, Web Content Filter, Notifications, and the Icons Extract from .app window) accept a file dropped onto the window. If you drop several files, only the first one is used.