Start Auth
The startAuth API signals the start of an authentication scan. This call puts the gate into a "processing" mode,
where the gate acknowledges that your external authentication device wants to process an authentication. While in
processing mode, the gate LED blinks to indicate to the shopper that an authentication is in progress.
While in processing mode, your device holds an exclusive lock on the gate, and the gate will ignore signals from other
authentication peripherals (such as a QR code reader or credit card reader that are directly attached to the gate,
if supported in your store).
startAuth returns an authStarted boolean value:
- true - The gate has been successfully put into processing mode. Your device now holds an exclusive lock. An authEventId is provided for use in the subsequent processAuth call.
- false - The gate is busy processing another entry (from your device or a different auth peripheral), or another error occurred. A reason string will explain why the request was rejected.
The authTimeout property is a lock timer that you set. Your device holds the exclusive lock on the gate for only this duration. Once the timeout is exceeded, the gate returns to "idle" mode, the lock is released, and other authentication peripherals can serve shoppers at the gate. The authEventId from the startAuth call also becomes invalid after this timeout.
Note: Impact on store throughput: During the entire reservation window, the gate cannot process any other shoppers. If your store has high foot traffic, even a few seconds of unnecessary reservation time per shopper can meaningfully reduce the number of people who can enter the store per minute. Always aim to complete your authentication and call processAuth as quickly as possible.
Important: While authTimeout should be as low as possible, your integration MUST be designed to guarantee that processAuth is always called before authTimeout elapses, with some buffer. There must be no scenario where an authentication runs indefinitely. If your authentication cannot complete in time, call processAuth with DENIED before the timeout. If processAuth arrives after the timeout, it is rejected with LOCK_EXPIRED.
Clock Synchronization
Every request includes a timestamp, which Amazon checks against server time. Requests whose timestamp is too far from server time are rejected with STALE_REQUEST. Regularly sync your device clock with a reliable time source (e.g., via NTP). We recommend syncing at least once every hour, but you can adjust this based on your device; some devices keep time more accurately than others. Use the heartbeatInterval returned by emitHeartbeat to detect clock issues.
Request Body Input
| Field |
Required |
Type |
Description |
storeId |
Yes |
String |
Your external store identifier, provided to you by Amazon during store onboarding. |
deviceId |
Yes |
String |
The unique identifier of your authentication device that has been registered. |
timestamp |
Yes |
Long |
Unix timestamp in milliseconds when the request originated from your device. Used for clock drift detection. |
authTimeout |
No |
Long |
Total time (in ms) the gate will remain reserved for your device, with an upper bound of 15000ms (15 seconds). If not set, defaults to 15000ms.
Recommended: 5000-10000ms (5-10 seconds).
Important: The longer you set authTimeout, the longer the gate is blocked if your authentication is slow or your device fails to call processAuth. Keep this value as low as practically possible to maximize store throughput. |
Response Body Output
| Field |
Type |
Description |
authStarted |
Boolean |
Whether the gate was successfully reserved. |
reason |
String (nullable) |
Set only when authStarted is false. Values: LANE_BUSY, LANE_UNAVAILABLE, DEVICE_NOT_REGISTERED, STALE_REQUEST. |
authEventId |
String (nullable) |
Unique reference linking to this gate reservation. Required for processAuth. Only set when authStarted is true. |
timestamp |
Long |
Server-side timestamp when the response was generated. |
startAuthMetadata |
Array |
Reserved for future use. Currently returns an empty array. |
Response Example Success
{
"authStarted": true,
"authEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reason": null,
"timestamp": 1717545600150,
"startAuthMetadata": []
}
Errors
When startAuth fails, authStarted is false and reason is set to one of the following values:
| Reason |
Status |
Meaning |
Action |
LANE_BUSY |
409 |
The lane is currently processing an entry. This could be a previous startAuth that still holds the lock, or a shopper using another authentication method installed on the gate (e.g., QR code reader or credit card reader). |
Wait 3-5s and retry once. If still busy, show "Please wait." |
LANE_UNAVAILABLE |
503 |
The gate is offline or cannot be reached. |
Show "Gate unavailable." Do NOT retry. |
DEVICE_NOT_REGISTERED |
404 |
The deviceId is not registered at this store, either because the registration APIs were never called or the registration was deleted. |
Register the device with createDeviceRegistration (use getDeviceRegistrations to verify). You do not need to contact Amazon. |
STALE_REQUEST |
400 |
The timestamp is too far from Amazon's server time. |
Sync your device clock (e.g., via NTP) and retry once with a corrected timestamp. |
