# Getting started

> The TrustOrder REST API in short. Base URL, API key, live and test environments, the first request and how to fail open.

## Base URL

```text
https://api.uptools.io/v1/trustorder
```

Every path on these pages is relative to it. Requests and responses are JSON (`Content-Type: application/json`).

## API key

1. Sign in to the [upTools Console](https://console.uptools.io/) and enable TrustOrder under Products. It is free.
2. On the **Webshops and API keys** tab add your webshop (the host name only, for example `example.com`).
3. Create a key with **New key**. The Console shows it only once, so copy it right away.

Send the key in the `Authorization` header:

```http
Authorization: Bearer to_live_…
```

| Key prefix | Environment | What it sees |
|---|---|---|
| `to_live_` | live | the live reports of every connected shop |
| `to_test_` | test | test reports only, kept apart from live |

Use a test key while you build the integration. Reports sent with a test key never affect live verdicts.

## First request

Check that the key works and see which webshop it belongs to:

```bash
curl https://api.uptools.io/v1/trustorder/me \
  -H "Authorization: Bearer $TRUSTORDER_KEY"
```

```json
{
  "shop_id": 12,
  "shop_name": "Example shop",
  "domain": "example.com",
  "env": "live",
  "account_status": "approved",
  "daily_check_quota": 50000,
  "checks_today": 132
}
```

A new account starts as `pending`: checks work right away, and the reports it sends are stored but count only after approval.

## The integration in three calls

1. **Before the order:** hash the buyer's identifiers ([hashing](https://docs.uptools.io/trustorder/api/hashing/)) and ask for a verdict with `POST /check` ([check](https://docs.uptools.io/trustorder/api/check/)).
2. **After delivery:** report the outcome of the order with `PUT /signals/{order_ref}` ([signals](https://docs.uptools.io/trustorder/api/signals/)).
3. **When an order changes back:** withdraw its report with `DELETE /signals/{order_ref}`.

## Fail open

TrustOrder must never stop a sale. Treat every error, and every answer that takes longer than 1.5 seconds, as **allow**. The server answers fast with `503` when it cannot reach its data, so a client with a short timeout stays quick.
