Bring your Own Authorization Considerations
This section specifies how your authentication device and cloud service must handle responses from the Cloud Entry Signal API.
Error Handling
What should I do when startAuth or processAuth fails?
Check the reason field in the response. The possible reasons, their meaning, and the recommended action for each API are listed on the per-API pages:
How should I handle HTTP error codes?
| Code | Meaning | Action |
|---|---|---|
| 400 | InvalidRequestException | Fix request. Do not retry. |
| 429 | Rate limited | Wait per Retry-After header. |
| 500 | Unknown Amazon-side issue | Retry once after 1 second. |
Shopper Experience
What if the shopper leaves before auth completes?
If your device detects the shopper has left (e.g., face no longer in frame for 3 seconds):
MUST: Call processAuth with authResult = DENIED. This releases the gate reservation immediately.
What if my authentication takes too long?
Your budget = authTimeout - 5000ms. If your budget expires before auth completes, you MUST call processAuth(DENIED) immediately. Do NOT let the reservation expire silently - the shopper sees nothing and does not know what happened.
What if my device crashes during a gate reservation?
If your device becomes unresponsive while a gate reservation is active, your cloud service SHOULD detect unresponsiveness and call processAuth(DENIED) to release the gate.
How should I handle rapid re-scans?
| Situation | Action |
|---|---|
| Second scan while first flow is active | Ignore it. Complete or abandon current flow first. |
| Scan within 3s of successful entry | Ignore it. Cooldown prevents duplicate entries. |
| Scan after a denied result | Accept it - start a new flow from startAuth. |
Clock Synchronization
Why does clock synchronization matter?
All requests include a timestamp field. If your clock drifts too far from Amazon's server time, requests will be rejected as STALE_REQUEST.
How do I keep my clock in sync?
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.
Your heartbeat response includes a heartbeatInterval (Amazon server time minus the timestamp of your previous heartbeat). If it consistently deviates from your heartbeat frequency, your device clock may be drifting and you may need to sync more often. See Interpreting heartbeatInterval.
How much clock drift is acceptable?
| Drift | Impact |
|---|---|
| < 1 second | Normal - no action needed. |
| 1-3 seconds | Warning - sync your clock (e.g., via NTP) and consider increasing your sync frequency. |
| > 3 seconds | Critical - all requests will fail. Halt auth attempts until corrected. |
Timers
What timer values should I use?
| Timer | Value | Description |
|---|---|---|
authTimeout |
5000-10000ms | Total reservation time sent in startAuth. |
| Your auth budget | authTimeout - 5000ms |
Max time for your authentication logic (time between startAuth/processAuth calls). |
| Per-API-call timeout | 10000ms | How long to wait for Amazon response. Typical responses are much faster; this allows for latency regressions. |
| Post-entry cooldown | 3000ms | Wait after successful entry before next scan. |
| Heartbeat interval | 30000ms recommended | Must be at most 60000ms. |
Security
How are API requests authenticated?
All API requests are authenticated using AWS IAM (Signature Version 4). Your AWS credentials are provisioned during onboarding and are scoped to your merchant identity. Each API call is authorized at the store level, ensuring you can only interact with gates at stores you own.
What security best practices should I follow?
- Rotate your AWS credentials according to your organization's security policies.
- Never transmit shopper personally identifiable information (PII) to Amazon systems. The
personIdshould be an opaque, non-reversible identifier (do not use real names, emails, or phone numbers). - Use TLS 1.2 (Transport Layer Security) or higher for all API communications.
- Implement request signing (SigV4) correctly - see AWS documentation for implementation guides - unsigned requests will be rejected.
- Store credentials securely - never hard-code them or expose them in logs.
Endpoints
What are the API endpoints?
| Region | Endpoint |
|---|---|
| us-east-1 | https://us-east-1.api.amazonphysicalstores.com/auth/V2/ |
| us-west-2 | https://us-west-2.api.amazonphysicalstores.com/auth/V2/ |
The endpoint you must use can vary per store. Amazon will tell you which endpoint to use for each store during onboarding, so your integration must support configuring the endpoint per store rather than using a single endpoint for all stores.
Glossary
What do these terms mean?
| Term | Definition |
|---|---|
| Gate | A physical JWO entry barrier at a store. Can open or display visual/audio cues based on cloud commands. |
Lane (laneId) |
A logical identifier for a specific physical JWO gate. Provided manually by Amazon during onboarding (not through an API). |
| BYOA Device | Your authentication device (facial recognition camera, palm scanner, badge reader, etc.). |
| Onboarding | Initial setup process where your store, devices, and credentials are provisioned. Your store identifier (storeId) is assigned during this process. |
authEventId |
Unique reservation reference returned by startAuth linking your processAuth to the gate reservation. Valid only for authTimeout duration. On processAuth success, also links to the checkout payload under shoppingTrip.authEvents. |
authTimeout |
Lock timer (ms) you set in startAuth. How long the gate remains reserved. Recommended: 5000-10000ms. |
personId |
Your system's identifier for the authenticated person. An opaque string - do not include PII. Similar to shopperIdentity.id in the Create Purchases API. |
| Merchant Portal | The web portal where you view sales dashboards and metrics for your JWO stores. |
| SigV4 | AWS Signature Version 4 - the authentication protocol for signing all API requests. |
| CX | Customer Experience - visual and audio feedback displayed on the gate (success chimes, denied alerts). |
