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

# API Reference

> OAuth endpoints and how to use your access tokens with the OrderProtection API.

## Base URL

```
https://api.production.orderprotection.com
```

## OAuth endpoints

These endpoints handle authentication and token management for your app.

### Exchange tokens

```
POST /v1/oauth/token
```

Exchange an authorization code, refresh token, or client credentials for access tokens. See [Authentication](/developer/authentication) for detailed examples.

| Parameter       | Type      | Description                                                    |
| --------------- | --------- | -------------------------------------------------------------- |
| `grant_type`    | string    | `authorization_code`, `refresh_token`, or `client_credentials` |
| `client_id`     | string    | Your app's client ID                                           |
| `client_secret` | string    | Your app's client secret                                       |
| `code`          | string    | Authorization code (for `authorization_code` grant)            |
| `redirect_uri`  | string    | Must match the URI used during authorization                   |
| `code_verifier` | string    | PKCE verifier (if code challenge was used)                     |
| `refresh_token` | string    | Refresh token (for `refresh_token` grant)                      |
| `store_id`      | string    | Target store (for `client_credentials` grant)                  |
| `scopes`        | string\[] | Scope filter (for `client_credentials` grant)                  |

**Response:**

```json theme={null}
{
  "access_token": "op_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "op_rt_...",
  "scope": "read_orders read_claims"
}
```

***

### Revoke a token

```
POST /v1/oauth/revoke
```

Revoke an access or refresh token.

| Parameter         | Type   | Required | Description                       |
| ----------------- | ------ | -------- | --------------------------------- |
| `token`           | string | Yes      | The token to revoke               |
| `client_id`       | string | Yes      | Your app's client ID              |
| `client_secret`   | string | Yes      | Your app's client secret          |
| `token_type_hint` | string | No       | `access_token` or `refresh_token` |

**Response:** `200 OK` on success.

***

### Verify session token

```
POST /v1/oauth/session/verify
```

Verify an embedded app session token and retrieve user context. See [Embedded Apps](/developer/embedded-apps) for details.

| Parameter       | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `session_token` | string | Yes      | The JWT session token from the iframe URL |

**Response:**

```json theme={null}
{
  "userId": "user_abc123",
  "email": "merchant@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "storeId": "store_xyz789",
  "installationId": "inst_def456",
  "applicationId": "app_ghi012",
  "clientId": "op_app_...",
  "scopes": ["read_orders", "read_claims"]
}
```

<Note>
  This endpoint is rate-limited to 30 requests per minute per IP address.
</Note>

***

## Using access tokens

Once you have an access token, include it in the `Authorization` header of every API request:

```bash theme={null}
curl -X GET https://api.production.orderprotection.com/v1/orders \
  -H "Authorization: Bearer op_at_af444635983c457a5e..."
```

Your access token is scoped to the store that installed your app and the permissions the merchant granted. You can use it to call any OrderProtection API endpoint that falls within your granted scopes.

### Available APIs

With a valid access token, you can access these OrderProtection APIs:

<CardGroup cols={2}>
  <Card title="Orders" icon="box" href="/api-reference/orders/get-all-orders">
    Read and manage orders. Requires `read_orders` or `write_orders` scope.
  </Card>

  <Card title="Claims" icon="file-lines" href="/api-reference/claims/get-claims">
    Read and manage claims. Requires `read_claims`, `write_claims`, or `manage_claims` scope.
  </Card>

  <Card title="Products" icon="tag" href="/api-reference/products/get-product">
    Read and manage products. Requires `read_products` or `write_products` scope.
  </Card>

  <Card title="Fulfillments" icon="truck" href="/api-reference/fulfillments/get-fulfillments-for-order">
    Read and manage fulfillments. Requires `read_orders` scope.
  </Card>

  <Card title="Partner API (v2)" icon="key" href="/developer/endpoints">
    Manage settings, pricing rules, quotes, widgets, and A/B-test contexts via OAuth. Partner-only endpoints under `/v2`.
  </Card>
</CardGroup>

## Error responses

When a request fails, the API returns a JSON error response:

```json theme={null}
{
  "statusCode": 403,
  "message": "Insufficient scope: read_analytics required",
  "error": "Forbidden"
}
```

### Common error codes

| Code  | Description                                                  |
| ----- | ------------------------------------------------------------ |
| `400` | Bad request — check your request body or parameters          |
| `401` | Unauthorized — your token is invalid, expired, or revoked    |
| `403` | Forbidden — your token does not have the required scope      |
| `404` | Not found — the resource does not exist or is not accessible |
| `429` | Too many requests — you have exceeded the rate limit         |

<Tip>
  If you receive a `401` response, try refreshing your access token. If that also fails, the merchant may have uninstalled your app.
</Tip>