Developer Console
Sign In
Sign In
Developer Console

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

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

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.

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