AccountLogin Cluster

Cluster ID: 0x050E  |  Endpoint: Media endpoint (streaming device, content app on smart TV)

AccountLogin handles content provider account authentication on smart TVs or streaming devices. When a user's phone app is already logged into a video service (e.g., Netflix, YouTube) and wants the corresponding content app on the TV to also gain access to that account, this Cluster handles the authentication. It does not handle playback control (that's MediaPlayback's job), but rather solves the problem of "how does the TV know who you are".

Authentication Flow

AccountLogin authentication is a three-step handshake process, driven by the phone app (Commissioner):

1. Request PIN: The phone app sends GetSetupPIN to the content app on the TV, carrying a temporary account identifier (TempAccountIdentifier). This identifier is generated by the content provider app on the phone, typically a temporary token associated with the user's account
2. Receive PIN: After validating the temporary identifier, the TV-side content app returns a temporary Setup PIN (max 8 characters). This PIN is single-use, intended for the next login step
3. Execute Login: The phone app sends the Login command with the temporary identifier and Setup PIN together; after the TV-side verification succeeds, the node gains content access privileges

Commands

The AccountLogin Cluster has 3 commands and 1 response. GetSetupPIN has a dedicated response structure GetSetupPINResponse, while Login and Logout return results via a generic Status. Click a command ID in the table below to jump to its detailed description.

GetSetupPIN — Request Setup PIN (0x00)

Sent by the phone app (Client) to the content app on the TV (Server), requesting a temporary Setup PIN. Upon receiving the request, the content app queries user account information based on TempAccountIdentifier, and if valid, generates and returns a temporary PIN.

↑ Back to Commands

GetSetupPINResponse — Return Setup PIN (0x01)

The TV-side content app's response to GetSetupPIN. If the temporary account identifier is valid, returns a temporary PIN usable for Login.

↑ Back to Commands

Login — Log In (0x02)

Completes login using the previously obtained temporary account identifier and Setup PIN. After successful login, the requesting node gains access to the content app and can browse and play the user's subscribed content.

↑ Back to Commands

Logout — Log Out (0x03)

Revokes access privileges previously obtained through Login. After logout, the corresponding node can no longer access the content app's user content.

↑ Back to Commands

Attributes

The AccountLogin Cluster has no application-level custom attributes. It only contains global attributes required by the Matter specification (Global Attributes), which describe the Cluster's meta-information.

Security Mechanisms

AccountLogin involves user account authentication, with higher security requirements than ordinary control Clusters. The Matter specification imposes the following constraints:

Timed Invoke

All three commands must be sent using Timed Invoke. How Timed Invoke works:

1. Client first sends a TimedRequest, declaring the timeout for the subsequent command
2. Server replies with acknowledgment and starts the timer
3. Client sends the actual command (e.g., Login) within the timeout window
4. After the timeout window closes, Server no longer accepts the command

The core purpose of this mechanism is to prevent replay attacks: even if an attacker intercepts the complete Login command packet, it cannot be resent after the timeout window closes.

Temporary PIN Mechanism

Setup PIN is the second line of defense in the authentication flow:

• PIN is dynamically generated by the TV-side content app, not a fixed password
• PIN is bound to a specific TempAccountIdentifier and cannot be used across accounts
• PIN should have a validity period (spec recommends as short as possible); even knowing the PIN, login fails after expiration
• PIN should be invalidated immediately after use to prevent reuse

Access Privilege Requirements

AccountLogin commands require Administer level access privilege. This means only nodes with administrator privileges in the device ACL can invoke these commands; normal Operate level privileges are insufficient.

Example Data

Cluster Attribute Read

Read all attributes of the AccountLogin Cluster (global attributes only):

{
  // --- Global Attributes ---
  "0xFFF8": [0, 1],            // GeneratedCommandList = [GetSetupPINResponse]
  "0xFFF9": [0, 2, 3],         // AcceptedCommandList = [GetSetupPIN, Login, Logout]
  "0xFFFB": [                   // AttributeList
    0xFFF8, 0xFFF9,
    0xFFFB, 0xFFFC, 0xFFFD
  ],
  "0xFFFC": 0,                  // FeatureMap = 0 (no optional features)
  "0xFFFD": 2                   // ClusterRevision = 2
}

GetSetupPIN Interaction Example

Phone app requests Setup PIN from the TV content app:

// Phone App → TV Content App: Request Setup PIN
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x00"              // GetSetupPIN
    },
    "commandFields": {
      "TempAccountIdentifier": "user_abc_token_20260901"
                                       // Temporary account identifier generated by the phone
    },
    "timedRequest": true,              // Must use Timed Invoke
    "interactionTimeoutMs": 10000
  }]
}

// TV Content App → Phone App: Return Setup PIN
{
  "invokeResponseMessage": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x01"              // GetSetupPINResponse
    },
    "commandFields": {
      "SetupPIN": "34567890"           // Temporary PIN for subsequent Login
    }
  }]
}

Login Interaction Example

Complete login using the obtained PIN:

// Phone App → TV Content App: Login with PIN
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x02"              // Login
    },
    "commandFields": {
      "TempAccountIdentifier": "user_abc_token_20260901",
      "SetupPIN": "34567890",          // PIN returned by GetSetupPINResponse
      "Node": "0x0000000012345678"     // Optional: specify the node ID to authorize
    },
    "timedRequest": true,
    "interactionTimeoutMs": 10000
  }]
}

// TV Content App → Phone App: Status = SUCCESS

Logout Interaction Example

Log out of the current account:

// Phone App → TV Content App: Logout
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x03"              // Logout
    },
    "commandFields": {
      "Node": "0x0000000012345678"     // Optional: specify the node ID to log out
    },
    "timedRequest": true,
    "interactionTimeoutMs": 10000
  }]
}

// TV Content App → Phone App: Status = SUCCESS

Common Scenarios