@amazon-devices/kepler-media-account-login

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the Release Notes.

The Kepler Media Account Login API provides a way for apps to report their authentication status to the system.

Remarks

Apps need to refresh the user's login status upon each launch, which is done by the Account Login API. There are two account login states: signed in, and signed out. By keeping the login status up-to-date, apps make sure that users have access to appropriate content and features. The interface allows apps to communicate a boolean value indicating whether a user is logged in, both at launch and whenever the login state changes. The system can also query this status as needed, enabling a personalized user experience.

Products can leverage this information to feature or filter content from services where the user is already authenticated, allowing for instant access to content.

The Account Login functionality offers two key components for managing authentication status: the updateStatus method, and the handleReadStatus callback function. The updateStatus method reports an app's current login status for real-time updates when the authentication state changes. The handleReadStatus callback function can respond to system queries about the app's current login status. Both methods use the StatusType for account status, with two possible values: SIGNED_IN and SIGNED_OUT.

Get started

Setup

Add the following library dependency to the dependencies section of your package.json file.
Copied to clipboard.
```
 "@amazon-devices/kepler-media-account-login": "~1.1.0",
 "@amazon-devices/headless-task-manager": "~1.1.0"
```

In your manifest.toml, add the following privileges required to access.

Note: When modifying the manifest entries, replace com.amazondeveloper.media.sample with your app's package ID, as seen in the following example.

Copied to clipboard.

 schema-version = 1

 [package]
 title = "<Your app title>"
 id = "com.amazondeveloper.media.sample"

 [components]

 [[components.interactive]]
 id = "com.amazondeveloper.media.sample.main"
 runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
 launch-type = "singleton"
 # The category "com.amazon.category.kepler.media" is only necessary for the primary component, which is identified in the [[extras]]
 # section of the manifest using the "component-id" value.
 categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

 [[components.service]]
 id = "com.amazondeveloper.media.sample.interface.provider"
 runtime-module = "/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"
 launch-type = "singleton"

 [processes]

 [[processes.group]]
 component-ids = ["com.amazondeveloper.media.sample.main"]

 [[processes.group]]
 component-ids = ["com.amazondeveloper.media.sample.interface.provider"]

 [offers]

 [[offers.interaction]]
 id = "com.amazondeveloper.media.sample.main"

 [[offers.service]]
 id = "com.amazondeveloper.media.sample.interface.provider"
 required-privileges = ["com.amazon.multimedia.privilege.session.manage"]

 [[message]]
 uri = "pkg://com.amazondeveloper.media.sample.main"
 # Match the privileges used in [[offers.interaction]]. If privileges are not added, then use "*".
 sender-privileges = ["*"]
 receiver-privileges = ["self"]

 [[offers.module]]
 id = "/com.amazondeveloper.media.sample.module@ISomeUri1"
 includes-messages = ["pkg://com.amazondeveloper.media.sample.main"]

 [[extras]]
 key = "interface.provider"
 component-id = "com.amazondeveloper.media.sample.main"

 [extras.value.application]
 [[extras.value.application.interface]]
 interface_name = "com.amazon.kepler.media.IContentLauncherServer"
 attribute_options = ["partner-id"]
 static-values = { "partner-id" = "<Your partner id>" }

 [[extras.value.application.interface]]
 interface_name = "com.amazon.kepler.media.IAccountLoginServer"
 attribute_options = ["Status"]
 # In this manifest example, we have both Content Launcher and Account Login interfaces defined.
 # Since the Account Login cluster should be handled by a service component instead of an
 # interactive one for responsiveness, we use "override_attribute_component" to redirect
 # calls for the "Status" attribute to the service component.
 override_attribute_component = { Status = "com.amazondeveloper.media.sample.interface.provider" }

 [needs]

 [[needs.module]]
 # The dot (.) after "media" is intentional in this format. This notation will be changed in a 
 # future release.
 id = "/com.amazon.kepler.media.@IAccountLogin1"

 [[needs.module]]
 id = "/com.amazon.kepler.media@IContentLauncher1"

Media apps often require integration with three key APIs:

Content Launcher Cluster API for finding and launching content
Kepler Media Controls API for controlling launched media
Account Login API for communicating Account Login status to the system

The Content Launcher and Kepler Media Control APIs are most often implemented as an interactive component, which handles Kepler media queries. This component is specified in the app manifest's extras section using the interface.provider key, as shown in the following TOML snippet and in the previous example.

Copied to clipboard.

[[extras]]
key = "interface.provider"
component-id = "<primary interactive component-id>"

The Account Login API is implemented as a service app, allowing the system to query Account Login status without waking up the entire app. The Account Login API uses a single "Status" attribute, which is handled by the service component. To ensure proper routing of login status attribute interactions, the app manifest must specify the service component using the override_attribute_component setting, as demonstrated in this TOML example and in the previous example:

Copied to clipboard.

override_attribute_component = { Status = "<service component-id implementing Account Login api>" }

Use this approach to optimize system performance and provide a clear separation between media control and account management functionalities.

Kepler Media Account Login API reference

Modules

Last updated: Oct 02, 2025

@amazon-devices/kepler-media-account-login

Remarks

Get started

Setup

Related topics

Modules