SSI Client API

This section describes the Simple Sign-in API included in the Appstore SDK. For a full API Reference, see the latest Appstore SDK API Reference.

• Common data types
  • RequestStatus
  • RequestId
  • Token
  • Link
• linkUserAccount method
  • linkUserAccount request and response
• getUserAndLinks method
  • getUserAndLinks request and response
• showLoginSelection method
  • showLoginSelection request and response
• recordMetricEvent method
  • recordMetricEvent request and response

Common data types

The following are common data types you might encounter when working with the Simple Sign-in (SSI) API.

RequestStatus

The RequestStatus enum indicates the status of requests that your app makes to the SSI methods. The response includes an enum value to denote whether the request has succeeded or failed. The following table shows the enum values and their descriptions.

Value	Description
SUCCESSFUL	SSI successfully processed the request.
FAILURE	SSI encountered a non-retryable error when processing the request.
RETRYABLE_FAILURE	SSI encountered a transient and retryable error when processing the request. For example, a time-out or service unavailable error.
NOT_SUPPORTED	SSI can't handle the request on the given device. For example, if the device is not upgraded to the latest software containing the SSI feature.
NOT_AVAILABLE	The SSI feature is supported but is currently unavailable due to certain suppression rules. Reasons include: - The feature is disabled for the user's marketplace. - The feature is blocked for a particular app. - The device is running on a mode for which the feature is not supported. Example modes might include: the child profile mode on Fire tablets, or non-member guest user mode on Fire TV.
DUPLICATE_REQUEST	App sent a duplicate request.
FEATURE_TURNED_OFF	The customer has turned off the feature.
INVALID_LINK_SIGNING_KEY_ENCRYPTION	Amazon can't decrypt the LinkSigningKey provided in the linkUserAccount() method's request.
INVALID_LINK_SIGNING_KEY	The LinkSigningKey provided in the linkUserAccount() method's request is not a valid private key for signing SSI tokens.

RequestId

SSI assigns a unique identifier to each request your app makes to SSI. The RequestId object is a wrapper for this ID.

Field	Type	Required (Y/N)	Description
id	String	Y	A unique ID assigned for this request.

Token

The Token is a complex type that represents both the link token and SSI token in the request and response objects.

Field	Type	Required (Y/N)	Description
token	String	Y	Encoded token payload.
schema	String	Y	Schema identifier of the token. Supported schemas are as follows. - Link Token: LINK-TOKEN-1.0 - SSI Token: SSI-TOKEN-1.0

Link

A Link represents the account linking relationship between a customer's Amazon user identity and their user identity from you, along with associated metadata.

Field	Type	Required (Y/N)	Description
linkId	String	Y	A unique ID assigned by Amazon that represents the account linking relationship between the customer identities.
amazonUserId	String	Y	Developer-scoped identifier for the Amazon user account that is part of the account linking relationship.
partnerUserId	String	Y	An opaque identifier issued by you to represent your user's identity during the account linking setup.
identityProviderName	String	Y	Name of the identity provider used by you to authenticate users in your system.
ssiToken	Token	Y	The SSI token issued by Amazon.
linkedTimestamp	long	Y	Timestamp (epoch) when account linking was set up.

linkUserAccount method

Use the linkUserAccount() method to initiate account linking for a user's app account. The solution allows N:N mapping between Amazon and app accounts. There can be multiple app accounts linked to an Amazon account, and an app account can be linked to multiple Amazon accounts simultaneously.

Before setting up account linking, the Simple Sign-in client prompts for the user's consent by displaying a user consent screen. On securing the user's consent, SSI stores link data along with linkToken on the Simple Sign-in server. If a user declines consent for account linking, the linking process ends and SSI discards the linkToken it received from you.

linkUserAccount request and response

The request object of the linkUserAccount() method uses the type LinkUserAccountRequest, which contains the following fields.

Field	Type	Required (Y/N)	Description
partnerUserId	String	Y	An opaque identifier used to represent your user's identity to Amazon. This identifier is used in de-duplication of account linking requests if the app account is already linked with their Amazon account.
identityProviderName	String	Y	The name of the identity provider you use to authenticate users signing into your apps. You can pick a meaningful string value to represent your identity provider.
userLoginName	String	Y	The login name associated with the app account to display on the user consent screen.
linkToken	Token	Y	A link token representing the account linking relationship. For definition of the type Token, see Token.
linkSigningKey	String	Y	The private key part of the LinkKeyPair, encrypted using AppStoreKeyPair→PublicKey corresponding to the app revision.

The response object uses the type LinkUserAccountResponse, which contains the following fields.

Field	Type	Required (Y/N)	Description
requestId	RequestId	Y	See RequestId in the Common data types section.
requestStatus	RequestStatus	Y	See RequestStatus in the Common data types section.
successCode	SuccessCode	N	For account linking requests successfully processed, the SuccessCode enum indicates a more granular status. Name: LinkAlreadyExists Description: An account linking relationship already exists for the given identity pair and the request has been de-duped. Name: LinkEstablished Description: The user's consent was sought and obtained and the account linking relationship setup successfully. Name: ConsentDenied Description: The user has declined consent for account linking and the request has been aborted.
linkId	String	N	A unique ID assigned by Amazon that represents the account linking relationship between the customer identities.

getUserAndLinks method

Use the getUserAndLinks() method to fetch Simple Sign-in related data for the active Amazon user on the device. The response includes the following data:

• The list of active linked accounts along with a new SSI token for each account.
• Your scoped identity of the Amazon user, used to scope the linkToken to an Amazon user during token generation.

getUserAndLinks request and response

The getUserAndLinks() method requests your (the developer's) identity.

Field	Type	Required (Y/N)	Description
identityProviderName	String	Y	The name of your identity provider. You can pick a meaningful string value for this name. It must be consistent with the one supplied to the linkUserAccount() method during account linking.

The response object uses the type GetUserAndLinksResponse, which contains the following fields.

Field	Type	Required (Y/N)	Description
requestId	RequestId	Y	See RequestId in the Common data types section.
requestStatus	RequestStatus	Y	See RequestStatus in the Common data types section.
amazonUserId	String	N	Your scoped identifier for the Amazon user account active on the device.
links	List<Link>	N	A collection of Link objects where each object represents a linked app user account. An empty collection is returned if the customer doesn't have any linked accounts.

showLoginSelection method

Use the showLoginSelection() method to display the sign-in screen to users in your app. Before initiating showLoginSelection(), your app should retrieve a friendly user-recognizable identifier (login name/email address/profile name) from the app server for each linked account returned by getUserAndLinks(). Include this data in the showLoginSelection() request. The app displays this data on the screen and helps customers easily recognize their linked app accounts.

showLoginSelection request and response

The showLoginSelection() method requests a map of login names for each linked app user account.

Field	Type	Required (Y/N)	Description
loginNames	Map<String, String>	Y	A map of linkId to a user-recognizable login name. Your app obtains linkId strings when it calls getUserAndLinks() to fetch all linked accounts and obtains a list of Link objects.

The response object uses the type ShowLoginSelectionResponse, which contains the following fields.

Field	Type	Required (Y/N)	Description
requestId	RequestId	Y	See RequestId in the Common data types section.
requestStatus	RequestStatus	Y	See RequestStatus in the Common data types section.
userSelection	UserSelection	N	An enum of the selection made by the customer on the login screen. Possible values are as follows: Name: ManualSignIn Description: The customer has chosen to ignore linked accounts and sign in manually. Name: LoginSelected Description: The customer has chosen an account to sign in from one of the linked accounts offered.
links	List<Link>	N	A collection of Link objects where each object represents a linked app user account. An empty collection is returned if the customer doesn't have any linked accounts.

recordMetricEvent method

Your app can use the recordMetricEvent() method to record an event 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 SSI.

recordMetricEvent request and response

The recordMetricEvent() request object uses the type SSIEventRequest, which contains the following fields.

Field	Type	Required (Y/N)	Description
event	SSIEvent	Y	For record metric event requests, the SSIEvent is an enum that provides the possible metrics that can be published. Values are: Name: LOGIN_SUCCESS Description: This represents a successful login using SSI. Name: LOGIN_FAILURE Description: This represents a login failure using SSI. Name: MANUAL_SIGNIN_SELECTED Description: This represents when customers choose to manually sign-in (during second and subsequent sign-in attempts) ignoring the previously linked account.
epochTimestamp	String	Y	Timestamp (epoch) when a particular event was triggered.
failureReason	FailureReason	N	FailureReason is an enum that represents the possible failure reason if there is a login failure using SSI. Mandatory in case of a LOGIN_FAILURE event. Values are: Name: UNAUTHORIZED Description: The user isn't authorized to log in. Name: BAD_REQUEST Description: The request is corrupted. Name: NOT_FOUND Description: The login page the user is looking for cannot be found. Name: FORBIDDEN Description: No log in opportunity is available. Name: INTERNAL_SERVER_ERROR Description: Something is wrong with the login.

The response object uses the type RecordMetricsEventResponse, which contains the following fields.

Field	Type	Required (Y/N)	Description
requestId	RequestId	Y	See RequestId in the Common data types section.
requestStatus	RequestStatus	Y	See RequestStatus in the Common data types section.

---

Last updated: Feb 17, 2026