---
title: "Request a user decision for an agent action"
method: POST
path: "/v1/approvals"
tags: ["Agent"]
---

# Request a user decision for an agent action

`POST /v1/approvals`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/approvals`
- Auth: HTTP bearer

Asks the signed-in user to approve one agent action before it runs: a `confirmation` for a sensitive operation on an exact resource revision, or an `elevation` that temporarily adds `requestedScopes`. Spacefast shows the user your rationale and the target, and nothing changes until they decide in Spacefast; an agent cannot approve its own request. The rationale, resource, requesting credential, and grant cannot change after creation. Read the decision with getApproval. Request an elevation only for an action the user asked for.

## Request body

- object
  - `kind` 'confirmation' | 'elevation', required
  - `operation` 'publish' | 'deploy' | 'version_rollback' | 'space_delete' | 'space_transfer' | 'team_access' | 'domain_purchase' | 'domain_dns_change', required
  - `requestedScopes` string[]
  - `rationale` string, required
  - `resource` object, required
    - `kind` 'team' | 'space' | 'version' | 'domain' | 'connector_run', required
    - `id` string, required
    - `revision` union: The resource revision. Required for every operation except team_access.
      - string
      - integer
    - `targetTeamId` string
  - `quote` unknown

## Response `201`

Response for status 201

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `approvalId` string, required
  - `requiresAction` object, required
    - `actionType` 'device_authorization' | 'confirmation' | 'elevation', required: Stable identifier for the out-of-band step that blocks the flow.
    - `instruction` string, required: The step a person must complete out of band.
    - `url` string, uri, nullable: Where to send the human to complete the step, when a destination exists.
    - `pollUrl` string, uri: Where to POST the continuationToken to poll this flow: `/v1/actions/resume`.
    - `continuationToken` string, required: Short-lived, principal-scoped capability for this flow. Present it to POST /v1/actions/resume to poll and complete. Single-use on completion. A secret: never log it.
    - `pollAfterSeconds` integer, required: Minimum seconds to wait before calling resume again.
    - `expiresAt` string, date-time, required: Deadline for the human step. Resume after this returns terminal `expired`; the token survives a short grace so resume can say so, but the flow can no longer be redeemed.

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

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