# PerTimeUse Platform API

All money is represented as integer USD microdollars. `$1.00` is `1,000,000` microdollars.

## Passwordless account authentication

`POST /api/auth/request-otp`

```json
{"email":"user@example.com","mode":"signin"}
```

`POST /api/auth/verify-otp`

```json
{"email":"user@example.com","mode":"signin","otp":"123456"}
```

The response creates an HTTP-only session cookie. The same endpoints support `mode: "register"`.

## OAuth 2.1-style authorization code with PKCE

Redirect the customer to:

```text
GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256
```

Exchange the returned code from the application backend:

```text
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code&code=...&redirect_uri=...&code_verifier=...
```

## Wallet

- `GET /api/wallet/balance`
- `GET /api/wallet/transactions?limit=50`

Both accept a PerTimeUse session or `Authorization: Bearer <access_token>`.

## Metered usage

Create a reservation before provider work starts:

`POST /api/usage/reservations`

```json
{
  "productID": "fullymask",
  "sessionID": "provider-session-123",
  "unit": "second",
  "maximumAmountMicros": 710000,
  "idempotencyKey": "start-provider-session-123"
}
```

Settle actual usage:

`POST /api/usage/reservations/{reservation_id}/settle`

```json
{
  "amountMicros": 355000,
  "quantityMicros": 5000000,
  "idempotencyKey": "settle-provider-session-123"
}
```

Cancel failed or unused work:

`POST /api/usage/reservations/{reservation_id}/cancel`

Every metering request uses a user-scoped OAuth access token. Applications never receive database credentials or permission to modify wallet rows directly.

## Developer applications

- `GET /api/developer/apps`
- `POST /api/developer/apps`

The secret returned after application creation is shown once. Redirect URLs must use HTTPS, except localhost development URLs.