--- title: "Unconfirmed account revocations and unresolved Billit refresh grants" method: GET path: "/v1/admin/integrations/orphaned-upstream" tags: ["admin"] --- # Unconfirmed account revocations and unresolved Billit refresh grants `GET /v1/admin/integrations/orphaned-upstream` ## Request - Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from) - URL: `https://api.patricia.app/v1/admin/integrations/orphaned-upstream` - Auth: HTTP bearer Account summaries and outbox-backed grant residuals, with separate counts that can overlap. A grant does not establish a charge. Unsupported grants require manual upstream removal. Pass tenant_id to scope. Read-only. Admin only. Do not act on worker-owned or unknown-state grants. ## Query parameters - `tenant_id` string, uuid, nullable: Scope to one tenant; omit for the platform report. ## Response `200` Successful Response - OrphanedUpstreamReport: Account summaries and unresolved grants. Their populations can overlap; neither count proves a charge. - `accounts` OrphanedAccount[] - `id` string, required: IntegrationAccount id. - `tenant_id` string, required: Owning tenant. - `provider` string, required: Provider still potentially billing for this account. - `app_slug` string, nullable: Connected app/platform slug. - `external_account_id` string, required: The provider-side account id we could not confirm revoked. - `disconnected_at` string, nullable: When we deactivated it locally (soft-delete time). - `failure` 'attempt_pending' | 'provider_error' | 'adapter_error' | 'revoked' | 'unsupported': What we know about the provider-side credential after a disconnect cycle. Account summaries list ``ATTEMPT_PENDING``, ``PROVIDER_ERROR`` and ``ADAPTER_ERROR``. These states can indicate a live credential and continuing charges. ``REVOKED`` and ``UNSUPPORTED`` are excluded from that account collection. Typed Billit refresh residuals appear separately in ``grants``, including terminal ``unsupported`` grants. - ``ATTEMPT_PENDING``: no final outcome has been recorded for this disconnect. It does NOT mean nothing was attempted — it also covers a call running right now and one whose result was not saved. Read ``RevokeRetryOwnership`` to tell those apart. - ``PROVIDER_ERROR``: the provider call failed (outage, timeout, HTTP error). Retrying can fix it. - ``ADAPTER_ERROR``: the fault is on OUR side and no provider answer was recorded, so retrying the same input changes nothing. Not quite the same as "the request never left": for the MCP path it never does, but a generic adapter can also die MID-call (``ADAPTER_BUG_EXCEPTIONS`` names that case), which leaves the provider's state genuinely unknown rather than untouched. Three shapes: our integration code is broken, which a deploy fixes; the debt cannot be built into an authenticated request, which is operator work because the missing part is data; or a signing key is absent, which is configuration. ``UpstreamRevokeOutcome`` carries the split. - ``REVOKED``: the provider confirmed the credential is gone. Carries a revoked-at timestamp. - ``UNSUPPORTED``: no kill was confirmed, and nothing is retried. A grant, or part of one, may still be live at the provider. - `retry_ownership` 'owned' | 'dead_lettered' | 'unowned', required: Whether anything is still trying to revoke a reported credential, as of this read. Being on the leak report never meant retries had stopped, and this is the field that says so. It is a snapshot taken while the report was built, not a promise about the future. - ``OWNED``: something still owes this credential a revoke and may yet perform it. Do not clean the credential up at the provider by hand — you would race that attempt. - ``DEAD_LETTERED``: the debt gave up retrying. Account summaries derive this from the outbox for the current disconnect or from a legacy failed status. Reconnect does not require clearance. Billit grant clearance records upstream removal separately. - ``UNOWNED``: no live retry was identified. A terminal unsupported Billit grant needs manual upstream removal, followed by exact-grant confirmation. For account summaries this can also describe an in-flight disconnect before it queues a debt. Wait for a known disconnect or offboard to finish before treating an account as abandoned. - `count` integer, required: Number of orphaned account summaries in scope. - `grants` OrphanedGrant[] - `outbox_id` string, uuid, required - `tenant_id` string, uuid, required - `provider` string, required - `app_slug` string, nullable, required - `grant_key` string, required - `integration_account_id` string, uuid, nullable, required - `external_account_id` string, required - `estate` string, nullable, required - `client_id` string, nullable, required - `owner_id` string, nullable, required - `pending_intent_id` string, nullable, required - `connected_external_account_id` string, nullable, required - `captured_at` string, date-time, required: Outbox creation time, not an account disconnect time. - `settled_at` string, date-time, nullable, required - `residual_leak_code` 'billit_refresh_token_unrevocable', required - `state` string, required - `retry_ownership` 'owned' | 'dead_lettered' | 'unowned', required: Whether anything is still trying to revoke a reported credential, as of this read. Being on the leak report never meant retries had stopped, and this is the field that says so. It is a snapshot taken while the report was built, not a promise about the future. - ``OWNED``: something still owes this credential a revoke and may yet perform it. Do not clean the credential up at the provider by hand — you would race that attempt. - ``DEAD_LETTERED``: the debt gave up retrying. Account summaries derive this from the outbox for the current disconnect or from a legacy failed status. Reconnect does not require clearance. Billit grant clearance records upstream removal separately. - ``UNOWNED``: no live retry was identified. A terminal unsupported Billit grant needs manual upstream removal, followed by exact-grant confirmation. For account summaries this can also describe an in-flight disconnect before it queues a debt. Wait for a known disconnect or offboard to finish before treating an account as abandoned. - `clearable` boolean, required: True for recognized, uncleared unsupported or dead-letter grants. - `grant_count` integer, required: Number of unresolved grants in scope. ## Other responses - `401`: Unauthorized - `403`: Permission denied (PERMISSION_DENIED) or email not verified (EMAIL_NOT_VERIFIED) - `422`: Validation error --- [API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)