Verify Identity Keys
The Identity Connector is a simple API provided to Amazon which will be called whenever a shopper scans their Scan Key Code at the JWO gate or when a store associate scans the associate device to identify the shopper while assisting the shopper. The Identity Connector provides an interface between the company's backend identity systems and Amazon’s Identity Gateway. When a shopper scans their Scan Key Code at the JWO gate, Amazon will call the Identity Connector and pass the shopper’s identity key. Once the shopper’s identity is received, the company can verify the shopper’s identity key and decide whether to allow them to shop in the store
Note: In the future, new attributes might be added. We recommend that you structure your code so that it can handle new attributes
gracefully
Operations
VerifyIdentityKeys
POST /v1/identity/identity-keys
The VerifyIdentityKey API at /v1/identity/identity-keys allows the company to authorize the shopper before allowing them to into the JWO store
Body parameter
{
"requestId": "string",
"identityKey": "string",
"storeId": "string",
"authEvent": {
"id": "string",
"timestamp": "2024-02-09T17:53:57Z",
"location": "ENTRY"
},
"keyChannel": "OPTICAL"
}
Data Field |
Required |
Description |
requestId |
Required |
[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]. The requestId field holds a unique identifier (UUID) that Amazon generates each time a request is made to the company Connector |
identityKey |
Required |
<= 1000 characters. The identityKey stores a UUID in the id field used by the shopper to identify themself at the beginning of their shopping trip. The identityKey string is Base64 encoded. The Company needs to decode the identityKey before it attempts to perform any validation logic |
storeId |
Required |
string <= 255 characters. The storeId field contains the store identifier that Amazon assigned to you during your onboarding process. If you have multiple stores, each store will have a unique identifier. You use this field to identify in which one of your store locations a shopper is requesting identity |
keyChannel |
Optional |
Enum: "OPTICAL" "RADIO" .The keyChannel object contains required information about the channeling mechanism through which the key was read. |
AuthEvent |
Required |
The authEvent object stores a UUID in the id field to keep track of each interaction, a timestamp of when the interaction occurred, and a location that tracks whether the interaction was at the ENTRY or EXIT gate |
Data Field |
Description |
Required |
id |
Required |
^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}. The authEvent.id field stores a UUID to keep track of each unique interaction with the JWO entry/exit gates. This id is unique to each interaction with a JWO gate and is different than the requestId. You must make sure that you handle multiple API calls using the same *authEvent.id idempotently |
timestamp |
Required |
The authEvent.timestamp stores the date and time the authEvent occurred in UTC format |
location |
Required |
Enum: "ENTRY" "EXIT". The Auth location is an enumerated string containing either ENTRY or EXIT, depending on whether the shopper is entering or exiting the store |
|
Example responses
> 200 Response
Example responses
{
"visitorDetails": {
"id": "string",
"type": "SHOPPER"
},
"shopperDeviceId": "string",
"paymentSource": {
"id": "string"
}
}
Data Field |
Required |
Description |
visitorDetails |
Required |
|
Data Field |
Description |
Required |
id |
Required |
<= 255 characters.The VisitorIdentity.id is a UUID used to identify the shopper in the Company identity store |
type |
Required |
Enum: "SHOPPER" "ASSOCIATE" "CASH_SHOPPER". The visitorDetails type field identifies the type of shopper. Currently, we support three types of shopper, SHOPPER and ASSOCIATE and CASH SHOPPER. CASH SHOPPER is only supported in specific stores. Please confirm is CASH SHOPPER is supported in your store. We use the SHOPPER type for regular shoppers who are paying with a credit or debit card. We use the ASSOCIATE type for store employees who are shopping in the store |
|
shopperDeviceId |
Optional |
<= 255 characters. The shopperDeviceId field contains a unique identifier for the shopper’s mobile device. If a shopper has more than one device, then each device will get its own unique shopperDeviceId. |
paymentSource |
Deprecated |
The paymentSource object contains optional information about the source of payment for this transaction. The object contains a single id field, which is required if the paymentSource field is present |
Data Field |
Description |
Required |
id |
Deprecated |
The paymentSource.id field contains a unique identifier for the shopper’s payment information. The company will use this information when charging the shopper for the shopping trip. |
|
Verify Identity Key example responses
Status |
Meaning |
Description |
201 |
OK |
Successful response |
400 |
Bad Request |
You will receive a 400 error message when the API call fails due to a validation error. |
429 |
Too Many Requests |
You will receive a 429 error message when the API is called too many times. When you receive a 429 error due to multiple calls to the API you will receive the following response. errorMsg: Too Many Requests |
500 |
Internal Server Error |
You will receive a 500 error message when the API call fails due to an error. |