Start Auth

Clock Synchronization
Request Body Input
Response Body Output
Response Example Success
Errors

POST /auth/v2/startAuth 

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.