Authenticating Users with Client Tokens

Before a user can trade, you need to create a client token for them. This token ties a Steam account to your merchant account and is used for all trading operations on behalf of that user. There are two ways to get a client token: call our API, or generate one locally on your backend.

Option 1: API Authentication

Make a POST request with your API key:

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

Field	Type	Required	Description
`clientSteamId`	string	Yes	User’s Steam ID 64 (must match `76561XXXXXXXXXXXX` format, 17 digits)
`clientTradeUrl`	string	Yes	User’s Steam trade URL, exactly `https://steamcommunity.com/tradeoffer/new/?partner=<partner>&token=<token>` (`partner` is 1-10 digits, `token` is 8 characters of `A-Z`, `a-z`, `0-9`, `_` or `-`).
`clientId`	string	No	Your own identifier for this user (max 128 chars). Stored on every trade.
`clientData`	object	No	User context for instant deposit collateral calculations. See fields below.

Unknown top-level body keys are rejected with 1001 VALIDATION_FAILED.

clientData Fields

The clientData object feeds into the risk model that determines how much instant credit a user qualifies for during deposits. totalWager, kycLevel, fiatDeposits and cryptoDeposits are the fields used in collateral calculations. When you call the API, any other keys inside clientData are dropped; a token you sign locally (Option 2) keeps whatever keys you put in it.

Field	Type	Description
`totalWager`	number	Total amount (USD, `0` or more) the user has wagered on your platform. Higher wager history increases the user’s external trust score and unlocks more instant credit.
`kycLevel`	integer	The user’s KYC verification level on your platform (`0` or more; values above 3 are scored as 3). Level 3 lowers the wager threshold used in risk scoring, so the same wager earns more instant credit.
`fiatDeposits`	boolean	Whether the user has made fiat deposits on your platform. Counts only together with `cryptoDeposits`.
`cryptoDeposits`	boolean	Whether the user has made crypto deposits on your platform. Both methods together lower the wager threshold as much as KYC level 3 does; KYC level 3 plus both methods gives the lowest threshold, and so the most credit per dollar wagered.
`registrationDate`	string (ISO 8601)	When the user registered on your platform. Accepted but not currently used for scoring.
`kycHash`	string	Opaque hash you compute from the user’s KYC identifiers. Accepted but not currently used for scoring.

All fields are optional. If omitted, they default to 0 or false in the risk calculation, which means the user gets the baseline collateral amount.

The more context you provide, the more instant credit your users can access. A user with high wager volume, KYC level 3, and both fiat and crypto deposits will qualify for significantly more collateral than one with no data.

Authenticating only signs a token; nothing is stored at that point. The clientData carried in the token is saved to the user’s record when they create a deposit or withdrawal with it. Issue a new token whenever the values change so the next trade uses current data. Response:

{
  "requestId": "...",
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

The token is valid for 24 hours. Re-authenticate users when the token expires.

Option 2: Local Token Generation

If you want to skip the network round-trip, you can sign the token locally using the jose library and your API secret.

import { SignJWT } from 'jose';

const secretKey = new TextEncoder().encode(YOUR_API_SECRET);

const token = await new SignJWT({
  merchantId: YOUR_MERCHANT_ID,
  client: {
    steamID: '76561198012345678',
    tradeUrl: 'https://steamcommunity.com/tradeoffer/new/?partner=12345678&token=AbCdEfGh',
    clientId: 'user-123',       // optional
    clientData: {               // optional, used for collateral calculations
      totalWager: 5000,
      kycLevel: 2,
      fiatDeposits: true,
      cryptoDeposits: false,
    },
  },
})
  .setProtectedHeader({
    alg: 'HS256',
    userId: YOUR_MERCHANT_ID,
  })
  .setIssuedAt()
  .setExpirationTime('24h')
  .sign(secretKey);

The token contains merchantId as a top-level claim and also carries it in the JWT header userId field so AssetPay can look up your API secret during verification. If you don’t know your merchant ID, contact support or check your dashboard.

Both methods produce identical tokens. The only difference is whether AssetPay’s server or your server does the signing. Local generation saves one network call per user session.

Using the Token

For all /client/* endpoints, pass the token in the Authorization header:

headers: {
  'Authorization': 'CLIENT_TOKEN_HERE'
}

For API-key-authenticated endpoints (/auth/authenticate-client, /secure/*), use the api-key header instead:

headers: {
  'api-key': 'YOUR_API_KEY'
}

Security & Architecture

Client tokens can be used directly from your frontend. You don’t need to proxy every API call through your backend. This works because AssetPay protects your balance through callbacks, not through token restrictions: Deposits don’t require any balance check from you. The user is sending you items, not taking them. Your backend gets notified via callbacks when the deposit completes, and you credit the user at that point. Withdrawals are protected by the initiated callback. When a user initiates a withdrawal, AssetPay sends a callback to your backend before purchasing anything. Your backend checks the user’s balance, deducts it, and responds with 200 to approve. If the balance is insufficient, respond with a rejection and the trade is cancelled. Nothing gets purchased until your backend says so. This means the typical architecture looks like:

Frontend calls AssetPay directly

The user’s browser uses the client token to fetch inventory, browse the market, and initiate trades.

AssetPay calls your backend

For withdrawals, AssetPay sends an initiated callback to your backend. Your backend validates the user’s balance, deducts it, and responds with 2xx to approve the purchase. To reject, respond with a 4xx (e.g. 402 Payment Required); 408 and 429 are retried instead. A 2xx whose body has "action": "reject", "status": "rejected", or an INSUFFICIENT_BALANCE error code also rejects.

Your backend processes results

As the trade progresses, your backend receives callbacks for each status change. Credit balances on completed, handle refunds on failed or reverted.

You can also call AssetPay from your backend if you prefer. The client token works from both frontend and backend. The callback approval mechanism protects you either way.

What about the API key?

Your API key (ap_...) should stay on your backend. It’s used for merchant-level operations like authenticating clients, fetching prices, and reading your wallet balance and ledger. The client token is the one that’s safe to expose to users.

API Key Scopes

Your API key needs the CORE_ACCESS scope to authenticate clients and use the /secure/* endpoints. Available scopes:

Scope	Grants access to
`CORE_ACCESS`	Client authentication (`/auth/authenticate-client`), trade URL checks, prices, the `/secure/*` merchant self-trade endpoints, and read-only trade queries
`LEDGER_READ`	Your wallet balance (`/v1/wallets/me/balance`) and wallet transaction history (`/v1/ledger/transactions`), plus the other dashboard ledger endpoints, not covered by this reference
`DEPOSITS_WRITE`	Dashboard crypto top-up endpoints, not covered by this reference
`WITHDRAWALS_WRITE`	Dashboard crypto payout endpoints, not covered by this reference
`PROFILE_READ`	Dashboard profile, statistics, trade history and trade export endpoints, not covered by this reference

A key without the scope a route needs gets 403 with error 1908 INSUFFICIENT_SCOPE. Grant only the scopes your integration uses. You can manage scopes and rotate keys from your dashboard.

Getting Started

Integration

Events & Webhooks

Reference

Authenticating Users with Client Tokens

Option 1: API Authentication

clientData Fields

Option 2: Local Token Generation

Using the Token

Security & Architecture

What about the API key?

API Key Scopes

​Option 1: API Authentication

​clientData Fields

​Option 2: Local Token Generation

​Using the Token

​Security & Architecture

​What about the API key?

​API Key Scopes

Option 1: API Authentication

clientData Fields

Option 2: Local Token Generation

Using the Token

Security & Architecture

What about the API key?

API Key Scopes