apple-device-management-mdm/mdm/checkin/gettoken.yaml

title: Get Token
description: Gets a token from the server.
payload:
  requesttype: GetToken
  supportedOS:
    iOS:
      introduced: '17.0'
      supervised: false
      requiresdep: false
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: true
      userenrollment:
        mode: allowed
    macOS:
      introduced: '14.0'
      devicechannel: true
      userchannel: true
      supervised: false
      requiresdep: false
      userenrollment:
        mode: allowed
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '1.1'
      supervised: false
      requiresdep: false
      userenrollment:
        mode: allowed
    watchOS:
      introduced: n/a
  content: Check-in protocol get token data request and response.
payloadkeys:
- key: MessageType
  type: <string>
  presence: required
  rangelist:
  - GetToken
  content: The message type, which requires a value of `GetToken`.
- key: TokenServiceType
  type: <string>
  presence: required
  rangelist:
  - com.apple.maid
  - com.apple.watch.pairing
  content: A string that specifies the service for the requested token.
- key: TokenParameters
  type: <dictionary>
  presence: optional
  content: Parameters that the system uses to generate the token.
  subkeys:
  - key: SecurityToken
    title: Security Token
    supportedOS:
      iOS:
        sharedipad:
          mode: forbidden
        userenrollment:
          mode: forbidden
      macOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: A security token to generate the server token. Required by the `com.apple.watch.pairing`
      service type.
  - key: PhoneUDID
    title: Phone Identifier
    supportedOS:
      iOS:
        sharedipad:
          mode: forbidden
        userenrollment:
          mode: forbidden
      macOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The identifier of the phone paired to the watch. Required by the `com.apple.watch.pairing`
      service type.
  - key: WatchUDID
    title: Watch Identifier
    supportedOS:
      iOS:
        sharedipad:
          mode: forbidden
        userenrollment:
          mode: forbidden
      macOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The identifier of the watch paired to the phone. Required by the `com.apple.watch.pairing`
      service type.
- key: UDID
  supportedOS:
    iOS:
      userenrollment:
        mode: forbidden
    macOS:
      userenrollment:
        mode: forbidden
    visionOS:
      userenrollment:
        mode: forbidden
  type: <string>
  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:
      userenrollment:
        mode: required
    macOS:
      userenrollment:
        mode: required
    visionOS:
      userenrollment:
        mode: required
  type: <string>
  presence: required
  content: The per-enrollment identifier for the device. The system requires this
    value if the enrollment type is a user enrollment.
- key: EnrollmentUserID
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      devicechannel: false
      userenrollment:
        mode: required
    visionOS:
      introduced: n/a
  type: <string>
  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.
- key: UserShortName
  supportedOS:
    iOS:
      sharedipad:
        mode: required
    macOS:
      devicechannel: false
    visionOS:
      introduced: n/a
  type: <string>
  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. When present, it indicates that the token is for the user channel.
- key: UserID
  supportedOS:
    iOS:
      sharedipad:
        mode: required
    macOS:
      devicechannel: false
    visionOS:
      introduced: n/a
  type: <string>
  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
    visionOS:
      introduced: n/a
  type: <string>
  presence: required
  content: The full name of the user.
responsekeys:
- key: TokenData
  type: <data>
  presence: required
  content: The token data. If the token is a string value, it needs to be a UTF-8-encoded
    string.
notes:
- title: ''
  content: |-
    A server that supports this request needs to include a `com.apple.mdm.token` value in the `ServerCapabilities` key of the MDM profile payload to enroll the device.

    This request allows devices to fetch security-related tokens from the server and to retrieve different types of tokens for the various services that need them. Each service has a unique identifier, and can pass a specific set of parameters for the server to use when generating the token. If the server doesn't recognize the service type, it needs to return a `400` HTTP response status.

    > Note:
    > The `GetBootstrapToken` request is a separate request specifically for the bootstrap token.
- title: Support access management for Managed Apple Accounts
  content: |-
    For the service type `com.apple.maid`, the Apple Identity Service requests this token when a Managed Apple Account is signing in, and then uses it to verify that the Managed Apple Account belongs to the same organization as the MDM server that enrolled the device. The token is a JSON Web Token (JWT) per RFC 7519 with the following claims:

    - `iss`: A `String`, per RFC 7519 section 4.1.1, that the server sets to the system-generated server identifier (`server_uuid`) that `AccountDetail` returns.
    - `iat`: A `NumericDate`, per RFC 7519 section 4.1.6, that the server sets to the timestamp of the token generation. The Apple Identity Service uses this value to limit the time that the token is valid.
    - `jti`: A `String`, per RFC 7519 section 4.1.7, that the server sets to a unique identifier (a random UUID) for the JWT. The Apple Identity Service uses this value to ensure that it only uses the token once.
    - `service_type`: A `String` that the server sets to the value of the `TokenServiceType` key in the `CheckIn` request, which needs to be `com.apple.maid`.

    Sign the JWT using the server's private key that corresponds to the RFC 3280 public key certificate that's registered with Apple Business Manager or Apple School Manager.
- title: Support Apple Watch pairing
  content: For the service type `com.apple.watch.pairing`, the MDM server requests
    this token to enroll an Apple Watch, with the request coming from the phone that's
    paired to the watch. The format of the token is implementation-defined, but the
    phone and watch MDM servers need to use the same format. The purpose of this token
    is to confirm the pairing relationship of the watch to the phone, and to ensure
    that the phone is already enrolled in an MDM server that belongs to the same organization
    as the watch MDM server. Ensure that the token is cryptographically protected
    against tampering, spoofing, and replay attacks.