# public-api

Integrator access: API keys with scopes and integrator webhooks (HMAC-signed callbacks). All other resources are shared with the web/mobile API and documented per scope.

## GET /integration

operationId: `getIntegrationHome`
Summary: Integration home: connections, webhooks, API keys, usage and portal links
API key scopes: `integration:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `IntegrationHome`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

Operator console "Integration" page (P9-T11, FR-PLAT-06): every non-retired banking connection with lifecycle, health, breaker, webhook registration and last event, event backlog, last reconciliation run and open exceptions, activation checklist progress; API key counts; 7-day usage; integrator webhook health; developer-portal links.

**API key scope:** `integration:read` (operator-level keys only, `X-Tenant-Id` = the operator id).

## GET /integration/api-keys/{apiKeyId}/requests

operationId: `listOperatorApiKeyRequests`
Summary: Recent requests of an API key (7 days, no bodies)
API key scopes: `integration:read`
Parameters: `apiKeyId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `limit` (query), `outcome` (query)
Responses: 200 `ApiKeyRequestLog`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

The last requests of any key of the operator (newest first) and the status breakdown over 7 days. Method, route template, status, duration and request id only.

**API key scope:** `integration:read` (operator-level keys only, `X-Tenant-Id` = the operator id).

## GET /integration/api-usage

operationId: `getOperatorApiUsage`
Summary: API usage per key across the operator (daily)
API key scopes: `integration:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `from` (query), `to` (query), `apiKeyId` (query), `environment` (query), `customerId` (query)
Responses: 200 `ApiUsageReport`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

Per-key totals and daily series (P9-T11). Days before yesterday come from the daily rollup; yesterday and today are live from the request log (a call appears within `API_REQUEST_LOG_FLUSH_MS`, 5 s by default). Covers every key of the operator: customer keys and operator-level keys.

**API key scope:** `integration:read` (operator-level keys only, `X-Tenant-Id` = the operator id).

## GET /integrator-webhooks

operationId: `listIntegratorWebhooks`
Summary: List integrator webhook endpoints
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query)
Responses: 200 `IntegratorWebhookPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

## POST /integrator-webhooks

operationId: `createIntegratorWebhook`
Summary: Register webhook endpoint
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Request body: `IntegratorWebhookWrite`
Responses: 201 `IntegratorWebhookCreated`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Not idempotent: the response carries the signing secret shown once. SSRF guard on the URL (`422`); at most 10 endpoints per customer (`409`).

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

**Step-up:** requires a verified step-up challenge for action `integrator_webhook.change` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation. API keys holding `webhooks:manage` may call it without a step-up; every create, update, secret rotation and deletion notifies the endpoint owners (`webhook_endpoint_changed`, staff or customer members with `webhooks.manage`), whoever made it (review W3-03, P4 S-14).

## GET /integrator-webhooks/{webhookId}

operationId: `getIntegratorWebhook`
Summary: Get webhook endpoint
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-None-Match` (header)
Responses: 200 `IntegratorWebhook`, 304, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

## PATCH /integrator-webhooks/{webhookId}

operationId: `updateIntegratorWebhook`
Summary: Update webhook endpoint
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-Match` (header, required)
Request body: `IntegratorWebhookWrite`
Responses: 200 `IntegratorWebhook`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 412 `Problem`, 422 `Problem`, 428 `Problem`, 429 `Problem`, default `Problem`

**Concurrency:** `If-Match` with the current `ETag` is required (`428` if absent, `412` if stale).

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

**Step-up:** requires a verified step-up challenge for action `integrator_webhook.change` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation. API keys holding `webhooks:manage` may call it without a step-up; every create, update, secret rotation and deletion notifies the endpoint owners (`webhook_endpoint_changed`, staff or customer members with `webhooks.manage`), whoever made it (review W3-03, P4 S-14).

## DELETE /integrator-webhooks/{webhookId}

operationId: `deleteIntegratorWebhook`
Summary: Delete webhook endpoint
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 204, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

**Step-up:** requires a verified step-up challenge for action `integrator_webhook.change` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation. API keys holding `webhooks:manage` may call it without a step-up; every create, update, secret rotation and deletion notifies the endpoint owners (`webhook_endpoint_changed`, staff or customer members with `webhooks.manage`), whoever made it (review W3-03, P4 S-14).

## GET /integrator-webhooks/{webhookId}/deliveries

operationId: `listWebhookDeliveries`
Summary: Delivery attempts
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query)
Responses: 200 `WebhookDeliveryPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

## POST /integrator-webhooks/{webhookId}/deliveries/{deliveryId}/redeliver

operationId: `redeliverWebhook`
Summary: Redeliver an event
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `deliveryId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 202 `WebhookDelivery`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

## POST /integrator-webhooks/{webhookId}/rotate-secret

operationId: `rotateIntegratorWebhookSecret`
Summary: Rotate signing secret (old valid 24 h)
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `IntegratorWebhookCreated`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

**Step-up:** requires a verified step-up challenge for action `integrator_webhook.change` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation. API keys holding `webhooks:manage` may call it without a step-up; every create, update, secret rotation and deletion notifies the endpoint owners (`webhook_endpoint_changed`, staff or customer members with `webhooks.manage`), whoever made it (review W3-03, P4 S-14).

## POST /integrator-webhooks/{webhookId}/test

operationId: `testIntegratorWebhook`
Summary: Send a test event
API key scopes: `webhooks:manage`
Parameters: `webhookId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `WebhookDelivery`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `webhooks:manage`.

**Level (P9-T08b):** `X-Tenant-Id` = a customer → that customer's endpoints; `X-Tenant-Id` = the operator → the operator-level endpoints (sessions of operator owners with `webhooks.manage`, operator-level keys with `webhooks:manage`).

## POST /sandbox/incoming-payments

operationId: `simulateSandboxIncomingPayment`
Summary: Simulate an incoming payment
API key scopes: `payments:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SandboxIncomingPayment`
Responses: 202 `SandboxSimulation`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Sandbox only (`wb_test_` keys and sandbox environments); `404 feature-disabled` elsewhere.

**API key scope:** `payments:write`.

## POST /sandbox/payments/{paymentId}/status

operationId: `simulateSandboxPaymentStatus`
Summary: Simulate a provider status for a payment
API key scopes: `payments:write`
Parameters: `paymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SandboxPaymentStatus`
Responses: 202 `SandboxSimulation`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Sandbox only (`wb_test_` keys and sandbox environments); `404 feature-disabled` elsewhere.

**API key scope:** `payments:write`.

## POST /sandbox/reset

operationId: `resetSandbox`
Summary: Reset sandbox deliveries and paused endpoints
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `SandboxReset`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

Sandbox only (`wb_test_` keys and sandbox environments); `404 feature-disabled` elsewhere.

**API key scope:** `webhooks:manage`.

## POST /sandbox/webhook-events

operationId: `simulateSandboxWebhookEvent`
Summary: Emit an integrator event
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SandboxWebhookEvent`
Responses: 202 `SandboxSimulation`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Sandbox only (`wb_test_` keys and sandbox environments); `404 feature-disabled` elsewhere. Events carry `data.sandbox: true`.

**API key scope:** `webhooks:manage`.