---
title: "Run Installation Action"
method: POST
path: "/api/integrations/installations/{installation_id}/actions/{action}"
tags: ["integrations"]
---

# Run Installation Action

`POST /api/integrations/installations/{installation_id}/actions/{action}`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/integrations/installations/{installation_id}/actions/{action}`
- Auth: none declared

Run a server-allowlisted lifecycle action against an installation.

See ``_ALLOWED_ACTIONS`` for the action -> existing-subsystem mapping. Any
other action id is a ``400 unsupported_action`` rather than a silent accept.
Every action is scoped to the caller's own identity and folder rung, so it
can never read or move another identity's setup, evidence, or credential.

## Path parameters

- `installation_id` string, uuid, required
- `action` string, required

## Headers

- `x-impersonate-identity-id` string, nullable

## Response `200`

Successful Response

- ActionResultOut: Outcome of a server-allowlisted installation action (``POST .../actions/{action}``). ``installation_state`` reflects the folder-level lifecycle after ``enable``/``disable``; ``setup_state``/``setup_step`` report the viewer's derived setup after ``configure``/``connect``/``reconnect``/``verify`` (``setup_state`` is ``configured`` only when the viewer is connected). ``aggregate_state``/``connected_for_viewer`` are the freshly recomputed verdict of ``verify``. ``credential`` is populated only by an explicit mint action and only for the calling identity. ``ok`` means the action executed; for ``verify`` the verdict is ``connected_for_viewer``, not ``ok``.
  - `installation_id` string, uuid, required
  - `action` 'connect' | 'reconnect' | 'disconnect' | 'verify' | 'configure' | 'mint_observer_key' | 'enable' | 'disable' | 'remove_from_library', required: Closed wire vocabulary for actions the generic UI may render.
  - `ok` boolean, required
  - `installation_state` string, nullable
  - `setup_state` string, nullable
  - `setup_step` string, nullable
  - `aggregate_state` 'setup_needed' | 'verifying' | 'connected' | 'partially_connected' | 'needs_attention' | 'disabled' | 'error': The single row-level state, computed from a definition's facet states.
  - `connected_for_viewer` boolean, nullable
  - `credential` MintedCredentialOut: A credential minted by an explicit action, returned exactly once. Only an action response ever carries ``raw_key``: it is hashed at rest and cannot be read back, so a re-mint issues a NEW key rather than re-returning this one. No read endpoint (catalog, detail, setup descriptor) ever includes this model.
    - `key_id` string, uuid, required
    - `name` string, required
    - `key_prefix` string, required
    - `raw_key` string, required
    - `created_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/5fdd1072e877?raw)