SSI Client APIs

This section describes the Simple Sign-in APIs 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 API
  • Request and Response
• GetUserAndLinks API
  • Request and Response
• ShowLoginSelection API
  • Request and Response
• RecordMetricEvent API
  • Request and Response

Common data types

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

RequestStatus

RequestStatus is an Enum type indicating the status of requests made to the SSI APIs. An Enum value is included in the response to denote whether the request has succeeded or failed. The following table shows different possible values and their meanings.

Name	Description
SUCCESSFUL	Indicates the request has been successfully processed.
FAILURE	Indicates a non-retryable error has been encountered while processing the request.
RETRYABLE_FAILURE	Indicates a transient and retryable error has been encountered while processing the request, such as a time-out or service unavailable error.
NOT_SUPPORTED	Returned when the request cannot be handled on the given device, such as if the device is not upgraded to the latest software containing the SSI feature.
NOT_AVAILABLE	Returned when the 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	Indicates a duplicate request made while another request has also been made.
FEATURE_TURNED_OFF	The customer has turned off the feature.
INVALID_LINK_SIGNING_KEY_ENCRYPTION	The LinkSigningKey provided in the linkUserAccount() API request cannot be decrypted on Amazon's end.
INVALID_LINK_SIGNING_KEY	Returned when the LinkSigningKey provided in the linkUserAccount() API request is not a valid private key for signing SSI tokens.

RequestId

RequestId wraps a unique identifier assigned by the SSI API for each request made from your app.

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

Token

The Token is a complex type used to represent both the link token and SSI token in the API 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 API

The linkUserAccount() API is used 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, link data along with linkToken is stored on the Simple Sign-in server. If a user declines consent for account linking, the linking process is aborted and the linkToken received from you is discarded.

Request and Response

The request object of this API 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 under Common data types.
requestStatus	RequestStatus	Y	See RequestStatus under Common Data Types.
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 API

The getUserAndLinks() API is used to fetch Simple Sign-in related data for the current active Amazon user on the device through the requesting app. The API response includes the following pieces of data.

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

Request and Response

The API 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() API 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 under Common data types.
requestStatus	RequestStatus	Y	See RequestStatus under Common Data Types.
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 API

The showLoginSelection() API is used to display the login screen to users. Before initiating showLoginSelection(), for each linked account fetched using getUserAndLinks(), the app should retrieve a friendly user-recognizable identifier (login name/email address/profile name) from the app server, and include this data in the request. This data is displayed on the screen and used to help customers easily recognize linked app accounts.

Request and Response

The API 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 under Common data types.
requestStatus	RequestStatus	Y	See RequestStatus under Common data types.
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 API

The recordMetricEvent() API is used to trigger an event that needs to be recorded for metric publishing. Simple Sign-in business metric reports can be downloaded in the Reporting tab of the Developer Console. These metrics can provide insights into the business value and impact of integrating with SSI.

Request and Response

The request object of this API 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 represent a succesful login using SSI. Name: LOGIN_FAILURE Description: This represent a login failure using SSI. Name: MANUAL_SIGNIN_SELECTED Description: This represent when customers choose to manually sign-in (during 2nd and subsequent sign-in attempts) ignoring the previously linked account.
epochTimestamp	String	Y	Timestamp (epoch) when 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 under Common data types.
requestStatus	RequestStatus	Y	See RequestStatus under Common data types.

---

Last updated: Mar 13, 2023