> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lojou.app/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> How to connect your app to other sellers' stores.

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](/en/authentication#api-key) is simpler and you can skip this guide.

## Flow overview

```mermaid theme={null}
sequenceDiagram
    participant S as Seller
    participant L as Lojou
    participant A as Your app

    A->>L: 1. Redirect the seller to the authorization screen (client_id, redirect_uri)
    S->>L: 2. Logs in and approves access
    L->>A: 3. Redirects back with ?code=...&state=...
    A->>L: 4. POST /v1/oauth/token (code + client_secret)
    L->>A: 5. access_token + refresh_token
    A->>L: 6. Uses the access_token on any /v1/* endpoint
```

## 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.

<Note>
  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.
</Note>

## 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

```bash theme={null}
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..."
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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.