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

# Authenticate Client

> Generate a client token for a Steam user.

# POST /auth/authenticate-client

Creates a JWT token for a Steam user, allowing them to access client endpoints (inventory, market, trading).

**Authentication:** API Key (`api-key` header, requires `CORE_ACCESS` scope)

## Request

```http theme={null}
POST https://api.assetpay.gg/auth/authenticate-client
Content-Type: application/json
api-key: YOUR_API_KEY

{
  "clientSteamId": "76561198012345678",
  "clientTradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=12345678&token=AbCdEfGh",
  "clientId": "user-123",
  "clientData": {
    "totalWager": 5000,
    "kycLevel": 2,
    "fiatDeposits": true,
    "cryptoDeposits": false
  }
}
```

### Body Parameters

| Parameter        | Type   | Required | Description                                                                                |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `clientSteamId`  | string | Yes      | Steam ID 64 (must match `76561XXXXXXXXXXXX` format, 17 digits)                             |
| `clientTradeUrl` | string | Yes      | Steam trade offer URL                                                                      |
| `clientId`       | string | No       | Your own user identifier (max 128 chars). Stored on every trade as `externalClientUserId`. |
| `clientData`     | object | No       | User context for collateral calculations. See `clientData` fields below.                   |

### clientData Fields

These fields feed into the risk model that determines instant deposit collateral. All are optional and default to `0`/`false`/`null` if omitted.

| Field              | Type              | Description                                                                                                                                           |
| ------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalWager`       | number            | Total USD amount the user has wagered on your platform. Higher values increase external trust score.                                                  |
| `kycLevel`         | number            | User's KYC verification level on your platform (0-3). Level 3 unlocks higher collateral thresholds.                                                   |
| `fiatDeposits`     | boolean           | User has made fiat deposits on your platform.                                                                                                         |
| `cryptoDeposits`   | boolean           | User has made crypto deposits on your platform.                                                                                                       |
| `registrationDate` | string (ISO 8601) | When the user registered on your platform. Older accounts get a small trust boost.                                                                    |
| `kycHash`          | string            | Opaque hash you compute from the user's KYC identifiers. Used by AssetPay to detect when a single verified identity links to multiple Steam accounts. |

Having both `fiatDeposits` and `cryptoDeposits` as `true` combined with `kycLevel: 3` gives the highest collateral multiplier. The `clientData` is updated on every authentication call, so pass current values each time.

## Response

```json theme={null}
{
  "requestId": "...",
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInVzZXJJZCI6Im1lcmNoYW50LXV1aWQifQ..."
  }
}
```

### Response Fields

| Field   | Type   | Description                                                  |
| ------- | ------ | ------------------------------------------------------------ |
| `token` | string | JWT signed with your API secret (HS256). Valid for 24 hours. |

## Token Structure

The generated JWT contains:

**Header:**

```json theme={null}
{
  "alg": "HS256",
  "userId": "your-merchant-id"
}
```

**Payload:**

```json theme={null}
{
  "merchantId": "your-merchant-id",
  "client": {
    "steamID": "76561198012345678",
    "tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=...",
    "clientId": "user-123",
    "clientData": { "totalWager": 5000, "kycLevel": 2, "fiatDeposits": true, "cryptoDeposits": false }
  },
  "iat": 1709550000,
  "exp": 1741086000
}
```

The `merchantId` claim and the JWT header `userId` field both carry the merchant ID. AssetPay uses either to look up your API secret during verification.

## Rate Limits

| Merchant Status | Limit                     |
| --------------- | ------------------------- |
| Verified        | 1,000,000 requests / hour |
| Unverified      | 100 requests / hour       |

## Errors

| Code | Key                        | When                                                            |
| ---- | -------------------------- | --------------------------------------------------------------- |
| 1001 | `VALIDATION_FAILED`        | Invalid Steam ID format, missing trade URL, etc.                |
| 1900 | `MISSING_API_KEY`          | No `api-key` header provided                                    |
| 1901 | `INVALID_API_KEY`          | API key not found or invalid                                    |
| 1903 | `API_KEY_SCOPE_DENIED`     | Key doesn't have `CORE_ACCESS` scope                            |
| 1915 | `NO_API_SECRET_CONFIGURED` | Merchant has no active API secret to sign the client token with |