Authentication

The Loops Partner API uses OAuth 2.0 client credentials. Your application has a client ID and secret for each environment.

Get a token

Your token URL, client ID and client secret are in the Loops Partners portal, under Applications. Each environment has its own.

curl -X POST $LOOPS_TOKEN_URL \
  -d grant_type=client_credentials \
  -d client_id=$LOOPS_CLIENT_ID \
  -d client_secret=$LOOPS_CLIENT_SECRET

{ "access_token": "eyJhbGciOi…", "expires_in": 900, "token_type": "Bearer" }

How tokens work:

• Tokens last 15 minutes. There is no refresh token; when a token expires, request a new one.
• Cache the token and reuse it until shortly before it expires. Don’t request a token for every call.
• Send it on every request: Authorization: Bearer <token>.

Name the merchant

One token works for all the merchants connected to your application. Every request says which merchant it is for:

GET /v1/orders HTTP/1.1
Host: api.partners.loops.sa
Authorization: Bearer eyJhbGciOi…
Loops-Merchant-Id: mer_7Hq2Lw8Z

If you built a direct integration for your own business, you have a single merchant and the header is optional.

Keep your secret safe

• Store the client secret in a secrets manager, never in source code or in an app installed on devices.
• Call the API from your servers, not from browsers or POS terminals.
• Rotate the secret in the Loops Partners portal. The old secret keeps working for 24 hours so you can deploy the change.
• If a secret leaks, rotate it immediately and tell us at partners@loops.sa.

When access is refused

Status	code	What to do
401	unauthorized	Get a new token
403	insufficient_scope	Your application isn’t approved for this scope. Request it in the portal.
403	scope_not_granted	The merchant didn’t grant this scope
403	connection_not_active	The merchant revoked access. Stop calling for this merchant.
400	merchant_required	Add the Loops-Merchant-Id header

See Errors for the full list.