OAuth - Lojou Docs

Use OAuth when your app will be installed by other sellers, not just run against your own store — each one authorizes access to their own store, without ever handing you their password or a permanent account-wide API key. If you only need to integrate your own store, an API key is simpler and you can skip this guide.

Flow overview

0. Register your app

First, you need a client_id and client_secret. This is done through the Lojou dashboard (not an API call) — contact support or register your app under Settings → Apps/Integrations to receive credentials and register your allowed redirect_uri(s).

1. Send the seller to authorize

Redirect the seller’s browser to Lojou’s authorization screen, with your app’s client_id and the redirect_uri (must match exactly what was registered in step 0):

https://web.lojou.app/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback

The seller logs into their own Lojou account (if not already logged in) and sees a screen with your app’s name and requested scopes, to approve or decline.

Confirm the exact URL for this screen with the Lojou team when you register your app (step 0) — what matters for your integration is the client_id/redirect_uri pair, which the API validates regardless of which page hosts it.

2. Handle the callback

If the seller approves, Lojou redirects back to your redirect_uri with two parameters:

https://yourapp.com/callback?code=eyJ...&state=aB3xY...

code — single-use, expires in 10 minutes.
state — the same value Lojou generated for this flow; use it to confirm the response matches an authorization you actually started (CSRF protection).

3. Exchange the code for a token

curl -X POST https://api.lojou.app/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "eyJ...",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
    "state": "aB3xY..."
  }'

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": "2026-09-30T12:00:00.000000Z",
  "permissions": ["orders.read", "products.read"]
}

Store the access_token and refresh_token scoped to that seller (one per connected store) — never to your app as a whole.

4. Call the API on the seller’s behalf

curl https://api.lojou.app/v1/orders \
  -H "Authorization: Bearer <access_token>"

Every /v1/* endpoint works the same whether the token came from OAuth or an API key — the only difference is how the token was issued.

Common errors

Error	Likely cause
`Invalid or expired code`	The `code` was already used once, or more than 10 minutes have passed. Restart the flow from step 1.
`Invalid state`	The `state` you sent back doesn’t match the one from the callback.
`client_id mismatch` / `redirect_uri mismatch`	The `code` was issued for a different `client_id`/`redirect_uri` than the ones you’re sending now.
`Invalid credentials`	Wrong `client_id`/`client_secret`, or the app is inactive.

Scopes

The seller only approves the scopes your app requested — and may approve a subset of them, depending on what they accept on the authorization screen. The permissions field in the token response tells you exactly what was granted; call GET /v1/scopes at any time to check again.

​Flow overview

​0. Register your app

​1. Send the seller to authorize

​2. Handle the callback

​3. Exchange the code for a token

​4. Call the API on the seller’s behalf

​Common errors

​Scopes

Flow overview

0. Register your app

1. Send the seller to authorize

2. Handle the callback

3. Exchange the code for a token

4. Call the API on the seller’s behalf

Common errors

Scopes