X-Authorization
header of your requests.
OAuth 2.0Scope | Value | Available Endpoints |
---|---|---|
Returns | returns | Process Return, Remove Line Items, Cancel Return, Flag Return, Close Return, Get Return Notes, Create Return Note, Detailed Returns List, Get Return Details, Advanced Shipping Notice, Grade Items, Assess Dispositions, Create Fraud Report |
Orders | orders | Create Return Deep Link, Create Return Deep Link with QR Code, List Blocklist Items, Get Blocklist Item, Create Blocklist Item, Delete Blocklist Item, List Allowlist Items, Create Allowlist Item, Get Allowlist Item, Delete Allowlist Item |
Carts | carts | Create Cart, Get Cart, Update Cart, Delete Cart |
Developer Tools | developer_tools | Get Webhooks, Create Webhook, Delete Webhook, Update Webhook |
Destinations (Read) | destinations:read | Get All Destinations, Get Destination Details |
Destinations (Write) | destinations:write | Create Destination, Update Destination, Delete Destination |
Happy Returns Shipments (Read) | happy_returns_shipments:read | Get Shipment Information, Get Shipments, Get Shipment Items |
X-Authorization
header.
An invalid API key will result in a 401 Unauthorized
response code. An API key is invalid if or lacks the required scopes for the requested endpoint.
Service | URL |
---|---|
OAuth Server | https://oauth.loopreturns.com |
API Server | https://api.loopreturns.com |
https://yourapp.com/install/loop
, when a Loop user wants to install your integration, they’ll be redirected to this URL, and your application should then redirect them to the OAuth authorization endpoint to begin the credential exchange process.
organization
query parameter to your Installation URL (e.g., https://yourapp.com/install/loop?organization=acme-corp
). You must capture this parameter and include it in your authorization request to Loop’s OAuth endpoint.Parameter | Required | Description |
---|---|---|
response_type | ✅ | Must be code |
client_id | ✅ | Your app’s client ID |
redirect_uri | ✅ | Must exactly match what you registered in the Google form |
scope | ✅ | Space-separated scopes (e.g. read:returns write:returns ). See Authentication for more on scopes. |
state | ✅ | Random string to prevent CSRF |
organization | ✅ | Organization identifier passed from Loop |
client_secret
is highly sensitive and should never be exposed to end users.Parameter | Required | Description |
---|---|---|
grant_type | ✅ | Must be authorization_code |
code | ✅ | The code received from the previous step |
redirect_uri | ✅ | Must match the original redirect URI |
client_id | ✅ | Your app’s client ID |
client_secret | ✅ | Your app’s client secret |
expires_in
field in the response indicates the number of seconds until the token expires. You’ll need to use the refresh token to obtain a new access token before it expires.Authorization
header.
POST https://oauth.loopreturns.com/oauth/token
endpoint with refresh_token
in the grant_type
parameter to obtain a new token.
Parameter | Required | Description |
---|---|---|
grant_type | ✅ | Must be refresh_token |
refresh_token | ✅ | The token you previously received |
client_id | ✅ | Your app’s client ID |
client_secret | ✅ | Your app’s client secret |
redirect_uri
exactly matches what you registered — including trailing slashes!client_secret
if you’re getting 401s from the token endpoint.state
parameter to prevent CSRF attacks.{resource}:{action}
read
(view data) or write
(create/modify data)Scope | Description |
---|---|
labels:read | Read access to labels |
labels:write | Create and modify labels |
label_requests:read | Read access to label requests |
label_requests:write | Create and modify label requests |
developer_tools | Create and modify webhooks |
invalid_request
, unauthorized_client
, access_denied
, unsupported_response_type
, invalid_scope
, server_error
, and temporarily_unavailable
.
redirect_uri
with error parameters:
client_secret
in client-side code, mobile apps, or public repositories.state
parameter prevents CSRF attacks and should be cryptographically secure: