title: Token Update description: Updates the token for a device on the server. payload: requesttype: TokenUpdate supportedOS: iOS: introduced: '4.0' supervised: false requiresdep: false sharedipad: mode: allowed devicechannel: true userchannel: true userenrollment: mode: allowed macOS: introduced: '10.7' devicechannel: true userchannel: true supervised: false requiresdep: false userenrollment: mode: allowed tvOS: introduced: '10.2' supervised: false visionOS: introduced: '1.1' supervised: false requiresdep: false userenrollment: mode: allowed watchOS: introduced: '10.0' supervised: false content: Check-in protocol token update request and response. payloadkeys: - key: NotOnConsole supportedOS: iOS: introduced: n/a macOS: introduced: '10.11' devicechannel: false visionOS: introduced: n/a watchOS: introduced: n/a type: presence: required content: If `true`, the device isn't on-console. - key: MessageType type: presence: required rangelist: - TokenUpdate content: The message type, which requires a value of `TokenUpdate`. - key: Topic type: presence: required content: The topic the device subscribes to. - key: UDID supportedOS: iOS: userenrollment: mode: forbidden macOS: userenrollment: mode: forbidden visionOS: userenrollment: mode: forbidden type: presence: required content: The device's UDID (unique device identifier). The system requires this value if the enrollment type is a device enrollment. - key: EnrollmentID supportedOS: iOS: introduced: '13.0' userenrollment: mode: required macOS: introduced: '10.15' userenrollment: mode: required tvOS: introduced: n/a visionOS: userenrollment: mode: required watchOS: introduced: n/a type: presence: required content: |- The per-enrollment identifier for the device. The system requires this value if the enrollment type is a user enrollment. Available in iOS 13 and later, macOS 10.15 and later, and visionOS 2 and later. - key: EnrollmentUserID supportedOS: iOS: introduced: n/a macOS: introduced: '10.15' devicechannel: false userenrollment: mode: required tvOS: introduced: n/a visionOS: introduced: n/a watchOS: introduced: n/a type: presence: required content: |- The per-enrollment identifier for the user. The system requires this value if the enrollment type is a user enrollment on the user channel. Available in macOS 10.15 and later. - key: UserShortName supportedOS: iOS: introduced: '9.3' sharedipad: mode: required macOS: devicechannel: false tvOS: introduced: n/a visionOS: introduced: n/a watchOS: introduced: n/a type: presence: optional content: |- For macOS, this value is the short name of the user. For Shared iPad, this value is the Managed Apple Account identifier of the user on Shared iPad. It indicates that the token is for the user channel. - key: UserID supportedOS: iOS: introduced: '9.3' sharedipad: mode: required macOS: devicechannel: false tvOS: introduced: n/a visionOS: introduced: n/a watchOS: introduced: n/a type: presence: optional content: |- For macOS, this value is the ID of the user. For Shared iPad, this value is `FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF` to indicate that authentication doesn't occur. - key: UserLongName supportedOS: iOS: introduced: n/a macOS: devicechannel: false tvOS: introduced: n/a visionOS: introduced: n/a watchOS: introduced: n/a type: presence: required content: The full name of the user. - key: Token type: presence: required content: The push token for the device. - key: PushMagic type: presence: required content: The magic string to include in the push notification message. - key: UnlockToken supportedOS: iOS: accessrights: AllowPasscodeRemovalAndLock sharedipad: mode: forbidden userenrollment: mode: forbidden macOS: introduced: n/a visionOS: accessrights: AllowPasscodeRemovalAndLock userenrollment: mode: forbidden watchOS: accessrights: AllowPasscodeRemovalAndLock type: presence: optional content: The data to use to unlock the device. If provided, the server needs to retain this data and send it when trying to implement `Clear-Passcode-Command`. - key: AwaitingConfiguration supportedOS: iOS: introduced: '9.0' macOS: introduced: '10.11' userchannel: false watchOS: introduced: n/a type: presence: optional default: false content: |- If `true` from the device channel, the device is awaiting a `Device-Configured-Command` command before proceeding through Setup Assistant. If `true` from the user channel (Shared iPad only), the device is awaiting a `User-Configured-Command` command before proceeding through Setup Assistant. notes: - title: '' content: |- The device sends an initial `TokenUpdate` message to the server when it installs the MDM payload. The server needs to send push messages to the device only after receiving the first `TokenUpdate` message. If the device reports that it is `AwaitingConfiguration`, the MDM server needs to send a `Device-Configured-Command` MDM command before the device allows the user to proceed in Setup Assistant. This gives the MDM server the opportunity to perform some setup using MDM commands. In addition to sending the initial `TokenUpdate` message, the device may send additional `TokenUpdate` messages to the check-in server at any time while it has a valid MDM enrollment. The use of `PushMagic` constrains the device to a unique MDM relationship. When a user removes the MDM profile, the device no longer listens to the former relationship, even if the user reestablishes a management relationship with the same server topic. Note that only the push topic is the same in this case; the server's address might change. This also helps when a user restores a device from backup that contains an older relationship. The use of `PushMagic` also ensures that the same organization owns both the server that receives the `CheckIn` message and the computer sending the push notifications. This is important because there's no way of knowing if the push topic belongs to the owner of the check-in server. It's conceivable that Apple might revoke a push token for one party, only to have that party reenroll people from some other topic that's actively pushing. The fact that all MDM push topics reside in the namespace `com.apple.mgmt.*` helps prevent this. The `PushMagic` or `UnlockToken` fields of subsequent `TokenUpdate` messages may be identical to those in previous messages, or may be different (and may differ in size from previous values). If different, the server needs to update its record for the device to the new values in the message. Failure to do so results in the server being unable to send push notifications or perform passcode resets. Although a device can send the `TokenUpdate` message multiple times, it might send it only once if the values in the message never change. Ensure your implementation doesn't rely on repeated messages to update lost server-side data or to recover from a failure to process a previous `TokenUpdate` message. Also note that `UnlockToken` is optional. Don't treat the absence of an `UnlockToken` in a `TokenUpdate` message as an invalidation of a previously received `UnlockToken`. > Note: > The topic string for the MDM check-in protocol needs to start with `com.apple.mgmt.*` where `*` is a unique suffix.