@amazon-devices/simplesignin
The Simple Sign-In Service API provides functionality that allows 3P app developers to link their the app accounts of their user account and the Amazon account which the customer used to register to the device. They can then use the linking to sign their user in seamlessly for subsequent login attempts.
The API enables the following functionality:
- Link the 3P app user's account with Amazon account.
- Get existing links for the users of a 3P app.
- Shows a selection screen with options for 3P app user for login.
- Record a business metric.
Get started
Setup
-
Add the following library dependency to the
dependenciessection of your package.json file."@amazon-devices/simplesignin": "~1.1", -
Add the following privilege in your manifest.toml.
[[wants.module]] id = "/com.amazon.dms.ssi@ISimpleSignIn" [[wants.service]] id = "com.amazon.dms.ssi.service" [[wants.interactive]] id = "com.amazon.dms.ssi.loginselection" [[wants.interactive]] id = "com.amazon.dms.ssi.consent"These permissions provide access to:
- Access the Simple Sign-In system service.
- Allows the screen that asks consent from the user.
- Allows the screen that shows login options to the user.
Usage
The following section shows how to perform account linking and login the user using Simple Sign-In.
GetUserAndLinks
The following sample initiates a request to fetch Simple Sign-in related data for the current active Amazon user on the device for your app.
let promise = SimpleSignInService.getUserAndLinks(IDP_NAME);
promise.then(
(response) => {
// Handle response
}
);
LinkUserAccount
The following sample initiates account linking for a user's app account. The example allows N:N mapping between Amazon and app accounts. Multiple app accounts can be simultaneously linked to an Amazon account, and an app account can be linked to multiple Amazon accounts.
let promise = SimpleSignInService.linkUserAccount(request);
promise.then(
(response) => {
// Handle response
}
);
ShowLoginSelection
The following sample opens a dialog that displays login options to users. Before calling this method, get the friendly user-recognizable identifier for each linked account and include the identifier in the request. To retrieve the identifiers call the getUserAndLinks() method. User-recognizable identifiers include login name, email address, or profile name. The code displays thes identifiers on the screen and to help customers easily recognize linked app accounts.
let promise = SimpleSignInService.showLoginSelection(request);
promise.then(
(response) => {
// Handle response
}
);
RecordMetricEvent
The following sample fires an event that is recorded for metric publishing. You can download Simple Sign-in business metric reports in the Reporting tab of the Developer Console. These metrics can provide insights into the business value and impact of integrating with Simple Sign-in.
let request = {
ssiEvent: SSIEvent.***,
timestamp : <epoch timestamp in milliseconds>,
failureReason = <FailureReason.***> // If SSIEvent is a Failure, then this field is mandatory.
};
let promise = SimpleSignInService.recordMetricEvent(request);
promise.then((response) => {
// Usually nothing to handle in this API.
});
Implementing the sign-in flow
Before implementing the sign-in flow, you'll need your Identity Provider Name (IDP_NAME), which is provided during your app's onboarding process in the Developer Console. This unique identifier connects your app to the Simple Sign-In service.
Getting Started with Sign-In
The sign-in process typically begins when:
- Your app launches
- A user clicks a login button
- A session requires authentication
The following example shows how to implement the basic sign-in flow using the GetUserAndLinks() method.
let getUserAndLinksPromise = SimpleSignInService.getUserAndLinks(IDP_NAME); // Calls the API
getUserAndLinksPromise.then( // Handle response
(response) => {
if (response.requestStatus != RequestStatus.SUCCESSFUL) {
// Check the requestStatus.
// Example, request is unsuccessul because user has disable Simple Sign-In for their account or this device or for this app.
// Fallback to show standard login of your app
} else if (response.links?.length! > 0) {
// It means there are links present using which user can login
/*
* Prepeare to ShowLoginSelection.
* This code is your customised code. You need to get the
* login names to show for each link to the user.
* You can the get the login names from the your server.
*/
let request:LoginNameValue[] = [];
response.links?.forEach((link) => {
request.push({loginName: <login-name-for-the-link>, linkId: link.linkId});
});
// Call ShowLoginSelection API
let showLoginSelectionPromise = SimpleSignInService.showLoginSelection(request);
showLoginSelectionPromise.then((response) => { // Handle what user has selected
if (response.userSelection == UserSelection.MANUAL_SIGN_IN) { // User selected to login with a new account
// Show your app's standard login
} else if (response.userSelection == UserSelection.LOGIN_SELECTED) { // User selected an existing link to login
// Pass the link id to appropriate method or to your app's server to authenticate
} else {
// Means user hasn't selected anything for 15mins, or there was a failure in request
// Fallback to show standard login of your app
}
});
} else {
// It means there are no links created yet for the user
// Fallback to show standard login of your app
}
}
);
Account Linking Process
After a successful standard login, you should link the user's account to enable seamless sign-in for future sessions. This process creates a secure connection between the user's Amazon account and your app's account.
The following sample links the user account to the app using your app's standard login method.
Every time the user signs in using the standard login process of your app, call the LinkUserAccount() method.
let request = {
partnerUserId: <partnerUserId>,
identityProviderName: <IDP_NAME>,
userLoginName: <login-name-for-the-user-account-to-show-to-user>,
linkToken: {
token: <token-that-your-server-has-generated>
schema: "LINK-TOKEN-1.0"
},
linkSigningKey: <link-signing-key-that-your-server-generated>
};
// Call LinkUserAccount API
let promise = SimpleSignInService.linkUserAccount(request);
promise.then((response) => { // Handle response
if (response.successCode == LinkAccountSuccessCode.LINK_ESTABLISHED) {
// Save the link id returned in the response corresponding the your app's user account on server.
// Use `response.linkId`.
} else if (response.successCode == LinkAccountSuccessCode.LINK_ALREADY_EXISTS) {
// Save the link id returned in the response corresponding the your app's user account on server as this is new link created.
// Use `response.linkId`.
} else if (response.successCode != LinkAccountSuccessCode.CONSENT_DENIED) {
// Means user doesn't want to link this account.
// Nothing to do at this point. Proceed with after login process of your app.
} else {
// There was some error from Simple Sign-In service. Check the requestStatus
// and report to Amazon if issue persists.
}
});
Troubleshooting
-
Consent screen or Login Selection Screen is not showing.
Make sure you manifest is updated.[[wants.module]] id = "/com.amazon.dms.ssi@ISimpleSignIn" [[wants.service]] id = "com.amazon.dms.ssi.service" [[wants.interactive]] id = "com.amazon.dms.ssi.loginselection" [[wants.interactive]] id = "com.amazon.dms.ssi.consent" -
API calls return
FEATURE_TURNED_OFFin request status.The user has disabled the Simple Sign-in feature at the account level, device level, or for your app.
-
API calls return
NOT_AVAILABLEin request status.The Simple Sign-in feature is not available in the region the device is running.
Enumerations
Classes
Type Aliases
- GetUserAndLinksResponse
- Link
- LinkUserAccountRequest
- LinkUserAccountResponse
- LoginNameValue
- RecordMetricsEventResponse
- ShowLoginSelectionResponse
- SSIEventRequest
- Token
Last updated: Oct 23, 2025
