Help center › Set up
Devices from Mosyle
Districts that manage iPads, iPhones, Macs and Apple TVs in Mosyle Manager need no devices file. On Admin › Import, the card Devices from Mosyle reads every device in your Mosyle Manager and makes each one an asset in Beacon, with its serial number, asset tag, model and school (and, if you choose, its Mosyle user as the holder), refreshed each night once you switch the nightly sync on. It signs in with your district's own Mosyle API token and a Mosyle administrator account you create for it. Beacon only ever reads; nothing is written back to Mosyle. If your Import page has no such card, Devices from Mosyle is not switched on for your organization; devices then come in from a CSV exported from Mosyle, matched by serial number (see Importing).
Before you start
- Mosyle Manager Premium. Mosyle's API, which Beacon reads, is part of Premium. Mosyle Business is a different product with a different API, and Beacon does not read it.
- An API access token. In Mosyle, open My School › API Integration and choose Add new token. Choose Public: Beacon's servers have no fixed outbound IP address to list. Mosyle shows the token once; copy it then.
- A Mosyle administrator account for Beacon. Since February 2024, Mosyle asks for an administrator's email and password with every API sign-in, besides the token. Create an administrator in Mosyle just for Beacon, with permission to view devices, and give it a Mosyle password. An account that signs in only through Google or Microsoft single sign-on, or that has a second factor, may be refused; if Mosyle refuses, the card says so. A dedicated account also keeps the sync running when a person changes their password or leaves the district.
Connect
On the card, paste the API access token, enter the email and password of the Mosyle administrator account you made for Beacon under Mosyle administrator email and Password, and click Connect Mosyle. Beacon signs in to Mosyle with them before saving anything: if Mosyle refuses, the reason appears under the form and nothing is kept. Once Mosyle accepts, the token and the password are stored encrypted and never shown again, to anyone. The card names the account and the token's last four characters (“token ending 1234”), so you can tell which token is saved.
Update credentials on the card takes a new token or a changed password the same way, with the same check; the form asks for the token and the password again each time, since Beacon never shows the saved ones. New credentials need their own preview before the next sync; saving them starts one.
Preview first, then sync
No device changes until you have looked. Connecting runs a preview on its own, and Preview runs one any time: it reads every device in Mosyle, counts what a sync would do (devices in Mosyle, how many would be added or changed, how many would be assigned to their Mosyle user, Shared iPads, devices in Lost Mode, devices no longer in Mosyle) and changes nothing. Once a preview has finished, Sync devices now runs the real pass, and Sync nightly keeps it current.
The settings
Three settings sit under the buttons, each saved the moment you change it.
- Assign devices to their Mosyle user (off to start). Off, the sync never assigns a device: who Mosyle has a device assigned to is information, and a technician checks devices out. On, a device with no holder is assigned to its Mosyle user, if that person is in Beacon (matched by email address). The trade-off is stated on the switch: a device whose user changes in Mosyle changes hands in Beacon. A device somebody already holds changes hands only when its Mosyle user changes; Shared iPads never get a holder; a sync never unassigns.
- Tag new devices with Mosyle's asset tag field (the default), the device name, or the serial number. A device with nothing in that field is tagged with its serial number. The same value is a second match key after the serial number, so a device you imported with that tag and no serial number is adopted, not duplicated; a device whose tag another device with its own serial number already carries is added with its serial number as the tag, and the card counts a tag conflict. A tag you corrected by hand stays until it changes in Mosyle.
- Sync nightly: every night after 02:00 in your organization's time zone; if no sync has run since the last 02:00, one starts within the hour of switching it on. It can be switched on once a preview has finished.
What is read, per device
| In Mosyle | In Beacon |
|---|---|
| Serial number | The match key. A device already in Beacon with that serial number is updated, never duplicated, so a fleet imported from a spreadsheet or from Incident IQ is enriched rather than doubled. A device without a serial number is skipped: there is nothing to match on. |
| Asset tag, device name | The asset tag of a device the sync adds comes from the field Tag new devices with names (Mosyle's asset tag by default). Whichever of the two is not the tag is kept with the device's external IDs, which the device page lists. |
| Model | The model, such as “iPad Air (5th generation)”; the manufacturer is Apple. The model identifier is kept with the device. |
| Type of device | The asset type: iPads go to iPad, iPhones and iPods to Phone, Macs to Mac, Apple TVs to Apple TV, Vision Pro to Apple Vision Pro. A type your organization lacks is created. The OS version is kept with the device. |
| Location | The device's site, when the location in Mosyle is spelled like the name or the code of one of your sites in Beacon (Admin › Sites). Otherwise the Mosyle user's site places it, when that person is in Beacon. |
| User | The person Mosyle has the device assigned to, by email address. Their site places the device when Mosyle's location names none of your sites. They become its holder only with Assign devices to their Mosyle user on. |
| Lost Mode | The status Lost (below). |
| Enrollment type | A Shared iPad never gets a holder (below). |
| UDID | Kept with the device's external IDs. |
| Last check-in, supervision, Wi-Fi MAC address, Mosyle's tags, the user's name and type, the Shared iPad cart | Kept with the device's external data. The API returns that data to technicians and administrators; the device page does not show it. |
A device the sync adds is In service, Assigned when the setting above gives it a holder, or Lost when it is in Lost Mode. Apart from Lost Mode, a status a technician set is never changed by the sync, and only an assignment moves a device from In service or In storage to Assigned. A Mac that Intune also manages is one asset, matched by serial number, carrying what each console knows.
Your edits survive
After a device's first pass, Beacon follows Mosyle only where Mosyle's own value changed since the previous pass, or where the field in Beacon was empty. A technician's In repair, a corrected tag or model, a check-out to someone else and a move to another site all stay while Mosyle repeats itself; a new model, a new asset tag (or device name, with that tag setting), a new location and a new Mosyle user are applied. Purchase date, cost, warranty, funding source and notes are never touched, except for the one note line below. A move to another site leaves the location and room behind, as a hand transfer does.
Lost Mode
When Lost Mode is switched on for a device in Mosyle, the next pass marks the asset Lost; when it is switched off, a lost asset returns to In service, or to Assigned if someone holds it. The device's history shows each change as made by the Mosyle sync. A device you marked lost by hand stays lost while Mosyle says nothing new: only a change in Mosyle moves it. Lost wins over an assignment. A device the sync adds while it is in Lost Mode starts as Lost; an asset already in Beacon that the sync finds in Lost Mode on its first pass becomes Lost only from In service or Assigned. Lost Mode itself is switched on and off in Mosyle, never from Beacon.
Shared iPads
An iPad enrolled as a Shared iPad is used by many people, so the sync never gives it a holder, with the setting on or off, and keeps none of its users' details. Its location still places it at a site, and the name of its cart in Mosyle is kept with the device. The card counts Shared iPads on each pass.
Devices gone from Mosyle
A device that disappears from Mosyle's listing is left exactly as it was. Once a pass has read that kind of device (iPads and iPhones, Macs, Apple TVs, Vision Pro) to the end, the device is flagged: its history says “Mosyle sync did not find this device in Mosyle (last seen date); it is flagged, not changed”, it gets a note line with the date it was last seen, and the card counts how many devices are flagged. A technician decides what that means: lost, retired, or removed from Mosyle by mistake. A device that comes back is un-flagged the same way, and the note line is removed; anything else you wrote in the notes stays. A pass that fails partway, or a listing Mosyle stopped before the end, flags nothing; the card says when a listing stopped early.
What Beacon never does
- It never writes to Mosyle. Beacon signs in, lists devices and reads them; it changes no device, user, location or setting in Mosyle, and Mosyle's own actions (Lost Mode, wipe, restart, app installs) are not offered in Beacon.
- It never deletes a device in Beacon, and never re-statuses one because it left Mosyle.
- It never shows the token or the password again once saved, to anyone, and never writes them to the audit log.
- It reads Mosyle Manager only. Jamf and SCCM are not read; those devices come in from an import by serial number.
When it runs, and what the card shows
Preview and Sync devices now run when you press them; the nightly pass runs after 02:00 in your time zone once the switch is on. The card shows the latest pass with its counts, each shown when it is not zero: in Mosyle, added, updated, assigned from the Mosyle user, Shared iPads, in Lost Mode, no longer in Mosyle, back in Mosyle, tag conflicts, skipped, errors. If Mosyle refuses Beacon's credentials, the card shows Needs attention with Mosyle's reason and the nightly pass pauses until you save them again. A temporary answer from Mosyle (a rate limit, an outage) only fails that pass, and the next one tries again.
Troubleshooting
Each message below is one the card can show, under the connect form or beside the last pass.
| The card says | What to do |
|---|---|
| Mosyle refused the sign-in. Check the API access token, and the administrator's email and password (the account must be able to sign in with a password), then save them again. Mosyle said: “Mosyle's reason”. The last sentence appears when Mosyle gave a reason. | Sign in to Mosyle in a private window with the email and password of the Mosyle administrator account you made for Beacon. If that needs Google or Microsoft, or a second factor, give the account a Mosyle password and no second factor, or create a dedicated one. Then use Update credentials (or Connect Mosyle) with the token and the password. |
| Mosyle no longer accepts Beacon's API access token. Create a new one under My School → API Integration in Mosyle and save it on the card. Mosyle said: “Mosyle's reason”. The last sentence appears when Mosyle gave a reason. | The token was removed or replaced in Mosyle, or was copied incompletely. Create a new Public token under My School › API Integration and save it with Update credentials. |
| Beacon could not read the saved Mosyle credentials (the server's encryption key changed). Save them again on the card. | Save the same token and password again with Update credentials. |
| Mosyle limited the request rate; the sync will run again at the next pass. Mosyle was unavailable; the sync will run again at the next pass. Mosyle had an internal error; the sync will run again at the next pass. Mosyle did not answer in time; the sync will run again at the next pass. Mosyle could not take the sign-in just now (“Mosyle's words”); the sync will run again at the next pass. Mosyle answered a code; the sync will run again at the next pass. | Nothing. The connection stays healthy and the next nightly pass tries again; Preview or Sync devices now later works too. Shown while connecting, nothing was saved: try again in a few minutes. |
| Beacon could not reach Mosyle: reason | A network problem between Beacon and Mosyle. Try again later; if it repeats for a day, email us the message. |
| Beacon could not reach Mosyle's API: the answer was HTTP code (“the answer's first words”), not from Mosyle. The sync will run again at the next pass. | Something between Beacon and Mosyle (a proxy, a firewall, an allowlist) answered instead of Mosyle's API, so your credentials were not judged and the connection stays healthy. Shown while connecting, nothing was saved: try again later. If it mentions an allowlist or an IP address, check that the token in Mosyle is Public. If it repeats for a day, email us the message. |
| Your district has tried to connect Mosyle 10 times in 15 minutes. Check the token, the email and the password in Mosyle, then try again in N minutes. | Each try signs in to Mosyle, so Beacon allows 10 in 15 minutes per district. Sign in to Mosyle in a private window with the email and password of the Mosyle administrator account you made for Beacon first, copy a fresh token if in doubt, then try once more after the wait. |
| Mosyle refused the device listing (code: reason). Mosyle could not list devices: reason. | The sign-in worked, but the device listing was refused; the text after the colon is what the answer said, usually Mosyle's own words. Check in Mosyle that the administrator account you made for Beacon can view devices, then run Preview again. |
| Mosyle accepted the sign-in but sent no token; the sync will run again at the next pass. Mosyle sent an answer Beacon could not read; the sync will run again at the next pass. Mosyle's device listing had an unexpected shape; the sync will run again at the next pass. | Mosyle answered in a way Beacon does not expect. The next pass tries again; if the message repeats, email us the message and the time. |
| Mosyle's iOS and iPadOS listing stopped before the end, so no device there was flagged as gone. | The pass still updated every device it read; only the check for devices gone from Mosyle was skipped for that kind of device. Nothing to do; if it says so every night, email us. |
| The Mosyle connection was removed or replaced while the sync was running; the pass stopped. | Expected after Update credentials or Disconnect during a pass. Run Preview on the new credentials. |
| Beacon restarted while the sync was running; the pass stopped and runs again shortly. The sync did not finish (the server restarted). It will run again. | Nothing; the next pass runs as usual. |
| Run a preview first: it shows what the sync would do without changing any device. | Click Preview, wait for it to finish, then sync. New credentials need their own preview. |
| A Mosyle sync is already running | Wait for it; the card refreshes every few seconds while a pass runs. |
| Devices from Mosyle is not included in your plan. Email hello@beaconhelpdesk.com for an order; the plans are at beaconhelpdesk.com/pricing. | Device sync is part of the District and Enterprise plans and the trial; Starter and Pro do not include it (Billing and plans). A connection made before a change of plan stays, with its devices; Preview, Sync devices now and the nightly pass wait until the plan includes device sync again. |
| Not available here (this organization is a demo district sandbox, or not active). | A demo district sandbox, and an organization that is not active, cannot connect Mosyle. Devices can still come in from a CSV exported from Mosyle. |
Disconnecting
Disconnect on the card deletes the saved token and password, and the nightly pass stops. The devices already synced stay exactly as they are. Beacon cannot revoke the token in Mosyle: remove it under My School › API Integration, and remove the Mosyle administrator account you made for Beacon if nothing else uses it. Connecting again later adopts the same devices by serial number.