Bring Your Own Auth
Overview
The Bring Your Own Auth (BYOA) API enables you, as a third-party partner, to integrate your own authentication devices (such as facial recognition cameras, palm scanners, or badge readers) with Just Walk Out(JWO) enabled store gates.
This integration allows your authentication device to signal Amazon's cloud to open the JWO gate remotely via a standardized Cloud Entry Signal API. In this model, your device authenticates the shopper, then signals Amazon's cloud through two sequential synchronous API calls. Amazon's cloud validates each request, and on the final call, sends a remote gate open command to the JWO gate hardware and returns the result back to your system.
Considerations
- Your authentication device and cloud service are fully owned and maintained by you. Amazon has no operational ownership of your device.
- Your device has no physical or network connection to the Amazon gate hardware. All communication happens via cloud APIs.
- The API is split into two sequential synchronous REST calls: startAuth (reserves the gate) followed by processAuth (delivers your auth decision and triggers gate action).
- Device Registration is a one-time setup to pair your authentication device with a specific JWO gate.
- A Heartbeat API must be integrated for Amazon to monitor the availability of your authentication device.
- All API calls are authenticated via AWS IAM Signature Version 4 (SigV4).
Once integration is complete, your shoppers will experience seamless gate entry using your authentication method, powered by Amazon's Just Walk Out technology.
Service Level Requirements
Your integration must meet the following performance and availability targets:
| Metric | Requirement | Notes |
|---|---|---|
| Availability | 99.95% | Your cloud service must be available for API calls. |
| Per-API-call Timeout | 5000ms | Maximum time your system should wait for a response from Amazon before treating it as a timeout. |
| Heartbeat Frequency | At least once per minute | Recommended: once every 30 seconds. |
Authentication
All API requests must be authenticated using AWS IAM (SigV4). Each merchant is provisioned with AWS credentials during onboarding. API calls are authorized at the store level, your credentials are scoped to the stores you own, preventing cross-merchant access.
Endpoint Infrastructure
All APIs are accessed via regional endpoints under the amazonphysicalstores.com domain. The specific subdomain and base URL will be provided during your onboarding process.
Idempotency
The processAuth API is idempotent - if you retry a processAuth call with the exact same inputs (same authEventId, personId, authResult), the system will not create a duplicate shopping journey. This is critical for safely handling timeout scenarios.
Integration Flow Overview
The following sequence describes the end-to-end integration flow from device setup through authenticating a shopper at the gate.
(identifier for a physical JWO gate) Partner->>Partner: Define deviceId
(your unique identifier for the device) Partner->>JWO: createDeviceRegistration
(map deviceId to laneId) loop At least once per minute (recommended: every 30 seconds) Device->>JWO: Heartbeat end Note over Shopper,JWO: Per-Shopper Authentication Flow Shopper->>Device: 1. Present to device
(face scan, badge tap, palm read, etc.) Device->>Partner: Forward shopper credentials Partner->>JWO: 2. startAuth JWO-->>Partner: authEventId
(gate reserved for your device) Partner->>Partner: 3. Authenticate the shopper Note over Partner,JWO: You must call processAuth before
the gate reservation expires.
Otherwise the gate releases the
reservation and the next shopper
can proceed. Partner->>JWO: 4. processAuth (authEventId, authResult) alt ACCEPTED JWO->>Shopper: Gate opens else DENIED JWO->>Shopper: Entry rejected end JWO-->>Partner: 5. Confirmation
(whether the gate acted on your decision)
After a successful processAuth (authResult = ACCEPTED), the authEventId (from startAuth response/processAuth request) will map to the shopper's cart and checkout process.
See the Create Purchases API documentation for more details on purchase processing. There, if you inspect the field shoppingTrip.authEvents, you will see a list of auth events with ids, each of which correlates with an authEventId from a startAuth/processAuth call.
