Magento’s REST API powers integrations from ERPs to mobile apps - and its authentication model trips up every newcomer at least once. Four auth mechanisms exist for different actors; choosing the right one and handling it properly is most of the battle. Here is the field guide.
The Four Auth Types
1. Integration tokens (the workhorse): created in System > Integrations, scoped to selected resources. A long-lived bearer token:
curl -H "Authorization: Bearer <token>" https://store.example.com/rest/V1/products/SKU-123
Use for server-to-server integrations. Scope the resource list to what the integration actually needs - a stock-sync integration does not need customer access.
2. Admin tokens: username/password exchanged for a token at /V1/integration/admin/token. Short-lived, full admin rights. Fine for scripts; never embed in shipped code.
3. Customer tokens: /V1/integration/customer/token for customer-context operations - mobile apps acting as the customer.
4. OAuth 1.0a: the original mechanism; still supported, rarely the right choice for new work.
The Rules That Save You
Bearer tokens on 2.4.4+: integrations now issue bearer tokens by default (older versions’ token-in-URL patterns are deprecated for good reason - URLs get logged). If an integration still puts tokens in query strings, modernise it.
Scope ruthlessly: the integration resource tree exists so a leaked token is a limited incident, not a full compromise. Audit integration ACLs quarterly.
Rotation: integration tokens can be rotated without downtime by creating a new integration, switching the consumer, then revoking the old. Have the procedure written before you need it.
Rate and Behaviour Expectations
Magento has no built-in REST rate limiting - protection belongs at the edge (Fastly, WAF, or web server rules). Without it, a runaway sync script can take the store down politely, one request at a time. On the consumer side: be a good citizen - batch where the bulk API exists, respect 429s and 5xx with backoff, and never poll in tight loops.
Error Handling Done Right
The API returns structured errors - read them:
401- token wrong/expired: re-authenticate once, then fail loudly (do not retry-loop)404- SKU/ID genuinely missing, or wrong store code400with a message - usually a validation failure; log the message, it says what is wrong
Log request ID, endpoint and response status for every call; the day an integration “stops working”, those logs are the difference between minutes and days of diagnosis.
Security Hygiene
- HTTPS only - tokens over HTTP are public tokens
- One integration per system, never shared credentials across systems
- Disable (not just forget) integrations when projects end
The REST API is stable, well-documented and battle-tested. Auth it correctly, scope it honestly, log it always - and it will carry your integrations for years without drama.