# Shadow Auth Tool – Reseller Integration Guide

Sell Shadow Auth Tool credits from your own DHRU Fusion panel, or integrate directly from your own software.
Credits move instantly from your reseller balance to your customer's account.

- **API URL (recommended):** `https://shadowauthtool.com/api/dhru`
- Use this one URL everywhere. If your panel adds `/api/index.php` to the end by itself, that works too.
- Older addresses that keep working: `https://shadowauthtool.com/dhru-api`, `https://shadowauthtool.com/api/v1/dhru/index.php`
- **Portal:** `https://shadowauthtool.com/reseller.html`

---

## 1. Requirements

| You need | How to get it |
|---|---|
| A reseller account | Your administrator creates it and gives you a username, a temporary password and an authenticator setup key (plus recovery codes). |
| A chosen password | Sign in at the portal with password + 6-digit authenticator code. You must replace the temporary password before anything else works. |
| An API key | Portal → **API access** → *Create API key*. Shown **once**. |
| A funded balance | Ask your administrator to add credits after payment. Every order deducts from this balance. |

**Strongly recommended:** enter your DHRU server's IP address in *Allowed IPs* when creating the key. The key is then useless from any other address.

---

## 2. Connect DHRU Fusion

*Settings → API Providers → Add API Provider*

| Field | Value |
|---|---|
| Provider name | Shadow Auth Tool |
| API URL | `https://shadowauthtool.com/api/dhru` (if your panel asks for a site address only, enter `https://shadowauthtool.com`) |
| Username | Your reseller username (the email on the account also works) |
| API key | The key from the portal (no spaces) |
| API type | DHRU |

### Test the connection

Use *Account Info / Balance*. Expected result:

```json
{"SUCCESS":[{"MESSAGE":"Account info retrieved successfully","Credit":"250.00",
 "AccoutInfo":{"mail":"you@example.com","username":"yourname","credit":"250.00","currency":"Credits"}}],
 "apiversion":"5.1"}
```

`Credit` is your **available** balance.

### Import services

Click *Sync Services*. You will see one group, **Credit top-up**, with these packs:

| Pack | Service ID | Cost to you |
|---|---|---|
| 1 credit | 100 | 1.00 |
| 2 | 200 | 2.00 |
| 5 | 500 | 5.00 |
| 10 | 1000 | 10.00 |
| 20 | 2000 | 20.00 |
| 50 | 5000 | 50.00 |
| 100 | 10000 | 100.00 |
| 250 | 25000 | 250.00 |
| 500 | 50000 | 500.00 |

Service ID = pack size × 100. A pack costs you exactly its size and gives the customer the same amount.
Set your own selling price in DHRU (for example 100 credits at 15 % margin → sell for 115 in your currency).

Each service asks for one custom field: **Username or email** of the customer's Shadow Auth Tool account.

### How an order flows

1. The customer orders a pack and enters their username or email.
2. DHRU calls `placeimeiorder`. The credits move **immediately**.
3. The order is `Success` (status 4) with the text *"10 credits were added to the account alice - check your account on https://shadowauthtool.com"*. Your panel shows this to the customer.

---

## 3. Protocol reference

All calls: `POST`, form-encoded (JSON body also accepted).

| Field | Meaning |
|---|---|
| `username` | Reseller username or email |
| `apiaccesskey` | Your API key |
| `action` | See below |
| `requestformat` | `JSON` |
| `parameters` | XML or JSON, optionally base64-encoded |

`parameters` can be sent as XML:

```xml
<PARAMETERS><ID>1000</ID><IMEI>alice</IMEI><REFERENCE>order-8841</REFERENCE></PARAMETERS>
```

or JSON `{"ID":1000,"IMEI":"alice","REFERENCE":"order-8841"}`. Direct integrations may instead send plain form fields (`customer=alice&amount=5`).

Success: `{"SUCCESS":[{...}],"apiversion":"5.1"}`
Failure (HTTP 200): `{"ERROR":[{"MESSAGE":"...","FULL_DESCRIPTION":"code"}],"apiversion":"5.1"}`

### Actions

| Action | Parameters | Returns |
|---|---|---|
| `accountinfo` | – | `Credit`, `AccoutInfo` |
| `imeiservicelist` | – | credit-pack catalog |
| `placeimeiorder` | `ID` (service id), customer in `IMEI`, `USERNAME`, `EMAIL` or `CUSTOMFIELD`; optional `REFERENCE` | `REFERENCEID` (order number) |
| `getimeiorder` | `ID` (order number) | `STATUS` (4 = success), `CODE` |
| `getimeiorderbulk` | `IDS` (comma separated, max 100) | `LIST` of statuses |
| `transfer` | `customer`, `amount` (max 2 decimals), optional `reference` | `REFERENCEID`, `AMOUNT`, `CREDIT` (your balance after) |
| `userinfo` | `customer` | `USERNAME`, `EMAIL`, `CREDIT`, `DISABLED` |
| `createuser` | `username`, optional `email`, optional `password` | `USERNAME`, `TEMPORARYPASSWORD` if generated |
| `listorders` | – | your last 100 transfers |

`fileservicelist`, `providerlist`, `modellist` and `mepkeylist` return empty lists so panel syncs don't fail.

### Examples

```bash
# Balance
curl -s https://shadowauthtool.com/api/dhru \
  -d username=YOURNAME -d apiaccesskey=hurs_xxxxxxxx -d action=accountinfo

# Send 25 credits to a customer (safe to retry: same reference never charges twice)
curl -s https://shadowauthtool.com/api/dhru \
  -d username=YOURNAME -d apiaccesskey=hurs_xxxxxxxx \
  -d action=transfer -d customer=alice -d amount=25 -d reference=inv-2026-0042

# DHRU-style order for a 10-credit pack
curl -s https://shadowauthtool.com/api/dhru \
  -d username=YOURNAME -d apiaccesskey=hurs_xxxxxxxx -d action=placeimeiorder \
  --data-urlencode 'parameters=<PARAMETERS><ID>1000</ID><IMEI>alice</IMEI><REFERENCE>order-8841</REFERENCE></PARAMETERS>'
```

### Idempotency – important

Always send a `REFERENCE`/`reference` (your order id). Repeating a call with the same reference **returns the original order and never charges again**. Reusing a reference with a different customer or amount is rejected (`reference_conflict`). Without a reference a retried request is treated as a new order.

---

## 4. Rules and limits

- Customers are found by exact username or email. The customer does not need a verified email; the username is enough. Disabled, administrator and reseller accounts cannot receive credits; you cannot credit yourself.
- Maximum per transfer: **1,000 credits** (can be raised by your administrator).
- Amounts have at most two decimals and must be positive.
- Orders fail with `insufficient_credits` if your available balance is too low – nothing is deducted.
- Rate limit: 240 requests / minute per IP. Ten failed authentications within five minutes block that IP for five minutes.
- Up to 5 active API keys; accounts you create with `createuser` (up to 5,000) are marked as yours.

---

## 5. Troubleshooting

| Message / code | Cause and fix |
|---|---|
| `Authentication Failed` | Wrong username/key, key revoked, spaces in the key, request not coming from the key's allowed IP, or reseller access removed. |
| `Too many failed authentication attempts` (HTTP 429) | Wait five minutes, then fix the credentials. |
| `password_change_required` | Sign in to the portal and replace the temporary password. |
| `insufficient_credits` | Balance too low – ask your administrator to top up. |
| `customer_not_found` | *This customer account wasn't found.* Usually a typo in the username or email; check it with the customer. Administrator and reseller accounts also give this answer. |
| `customer_unavailable` | The customer account is disabled. |
| `amount_too_large` / `invalid_amount` | Over the per-transfer cap, zero/negative, or more than 2 decimals. |
| `reference_conflict` | Reference already used for a different customer or amount. |
| `Invalid service ID` | Service ID is not one of the packs above – re-sync services. |
| Services missing after sync | Check the URL is exactly `https://shadowauthtool.com/api/dhru` (and starts with `https://`), then sync again. |
| Balance in DHRU differs from portal | Portal shows the same *available* credits; contact support with the response text (never your key). |

---

## 6. Security

- Treat the API key like a password. Never put it in public code, customer-facing pages or support tickets.
- Pin the key to your server's IP and revoke/recreate it if you suspect a leak (Portal → API access → Revoke).
- Every transfer is recorded in an append-only ledger and visible in *Recent transfers* in the portal.
- Reseller sign-in always requires your authenticator code; keep your recovery codes offline.