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

# Restrict Client-Side Reward Sending

> Disable client-side SendReward calls by adding an API version blocklist entry to enforce server-only rewards.

Block client-side `SendReward` calls by adding an API version blocklist entry to your Rewards App.

<Info>
  This step is optional but highly recommended for apps with high-value rewards or when you need complete control over reward issuance.
</Info>

<Warning>
  Enabling the blocklist rejects client SDK reward calls for this app. You can revert at any time by deleting the blocklist entry.
</Warning>

## Configuration

### Header Parameters

<ParamField required header="z-client" type="string" initialValue="developer-dashboard">
  Client identifier (use <code>"developer-dashboard"</code> )
</ParamField>

<ParamField required header="Authorization" type="string">
  Bearer token for authentication

  Format: `Bearer {JWT_TOKEN}`
</ParamField>

### Path Parameters

<ParamField required path="rewardsAppId" type="string">
  Your Rewards App ID
</ParamField>

### Body Parameters

<ParamField required body="version" type="number">
  API version to blocklist

  Use <code> 1 </code> to block client SDK calls (to block Send Reward v1)
</ParamField>

<ParamField required body="apiRoute" type="string">
  The API route to blocklist

  Use <code> "/earn/limited-achievement/reward" </code> to block client reward sending
</ParamField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "message": "API version blocklist created successfully.",
    "data": {
      "id": "e2fbc21e-b524-4304-aa55-b20941ede9f6",
      "rewardsAppId": "b28e0306-2c06-4092-8d56-a1623d6b97fb",
      "version": 1,
      "apiRoute": "/earn/limited-achievement/reward",
      "createdAt": "2025-10-29T14:06:50.321Z"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 400 - Bad Request theme={null}
  {
    "success": false,
    "message": "Invalid parameters"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "message": "Authentication required"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "success": false,
    "message": "Developer does not own this app"
  }
  ```

  ```json 409 - Conflict theme={null}
  {
    "success": false,
    "message": "Blocklist entry already exists"
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "success": false,
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Response Fields

| Field          | Type    | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| `success`      | boolean | Whether the request was successful               |
| `message`      | string  | Description of the result                        |
| `data`         | object  | Contains blocklist entry details                 |
| `id`           | string  | Unique identifier for this blocklist entry       |
| `rewardsAppId` | string  | Your Rewards App ID                              |
| `version`      | number  | API version that is blocklisted (Send Reward v1) |
| `apiRoute`     | string  | The API route that is blocklisted                |
| `createdAt`    | string  | ISO 8601 timestamp of when the entry was created |

***

### Response Status Codes

| Code  | Description                                 |
| ----- | ------------------------------------------- |
| `200` | Blocklist entry created successfully        |
| `400` | Bad request - invalid parameters            |
| `401` | Unauthorized - authentication required      |
| `403` | Forbidden - developer does not own this app |
| `409` | Conflict - blocklist entry already exists   |
| `500` | Internal server error                       |

## What Happens After Restriction?

After applying this blocklist:

<CardGroup cols={2}>
  <Card title="Client SDK Blocked" icon="xmark" color="#ef4444">
    Client SDK calls to send rewards will be rejected
  </Card>

  <Card title="Backend Server Active" icon="check" color="#22c55e">
    Server calls with API key will continue to work
  </Card>
</CardGroup>

### Client SDK Behavior

When a client tries to send rewards via v1 after the blocklist is applied:

```
Error: This endpoint requires API key authentication. Please use the API key endpoint instead.
```

### Server Behavior

Your backend server can continue sending rewards normally using the v2 endpoint with your API key.

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const rewardsAppId = 'YOUR_REWARDS_APP_ID';
  const jwtToken = 'YOUR_JWT_TOKEN';

  async function restrictClientRewards(rewardsAppId) {
    const response = await fetch(
      `https://api.zbdpay.com/api/v1/rewards/app/${rewardsAppId}/api-version-blocklist`,
      {
        method: 'POST',
        headers: {
          'z-client': 'developer-dashboard',
          'Authorization': `Bearer ${jwtToken}`
        },
        body: JSON.stringify({
          version: 1,
          apiRoute: '/earn/limited-achievement/reward'
        })
      }
    );

    const data = await response.json();

    if (data.success) {
      console.log('Client rewards restricted successfully!');
      console.log(`Blocklist entry ID: ${data.data.id}`);
      return data.data;
    } else {
      throw new Error(`Failed: ${data.message}`);
    }
  }

  // Apply restriction
  await restrictClientRewards('b28e0306-2c06-4092-8d56-a1623d6b97fb');
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.zbdpay.com/api/v1/rewards/app/{rewardsAppId}/api-version-blocklist' \
  --header 'z-client: developer-dashboard' \
  --header 'Authorization: Bearer {JWT_TOKEN}' \
  --data '{
    "version": 1,
    "apiRoute": "/earn/limited-achievement/reward"
  }'
  ```

  ```python Python theme={null}
  import requests
  import os

  jwt_token = os.getenv('JWT_TOKEN')
  rewards_app_id = "YOUR_REWARDS_APP_ID"

  def restrict_client_rewards(rewards_app_id):
      """Disable client-side reward sending"""

      url = f"https://api.zbdpay.com/api/v1/rewards/app/{rewards_app_id}/api-version-blocklist"
      headers = {
          "z-client": "developer-dashboard",
          "Authorization": f"Bearer {jwt_token}"
      }
      payload = {
          "version": 1,
          "apiRoute": "/earn/limited-achievement/reward"
      }

      response = requests.post(url, json=payload, headers=headers)
      data = response.json()

      if data["success"]:
          print("Client rewards restricted successfully!")
          print(f"Blocklist entry ID: {data['data']['id']}")
          return data["data"]
      else:
          raise Exception(f"Failed: {data['message']}")

  # Apply restriction
  restrict_client_rewards("b28e0306-2c06-4092-8d56-a1623d6b97fb")
  ```
</CodeGroup>

<Note>
  You only need to create a single block list entry with version 1 to disable client-side rewards. To re-enable client rewards, simply delete that block list entry.
  You can remove the blocklist entry at any time to re-enable client-side reward sending by deleting the blocklist entry.
</Note>

## What’s Next?

You’ve now restricted client-side reward sending and enforced backend-only control. Next, manage and secure your Rewards App:

* **[Manage via Dashboard](/earn/sdk/manage-via-dashboard)** — Create, list, and revoke API keys for your Rewards App.