# Request a user decision

Creates a confirmation or temporary scope-elevation request for an agent action and returns its ID inside a `requiresAction` envelope carrying the page to send the user to, the poll endpoint, and a continuation token. Only an agent spending a user-owned grant can ask, and only that grant’s owner can answer. The action is identified by its operation, resource, and revision, so asking again for the same action returns the same decision and a reworded `rationale` cannot open a fresh one.

## POST `/v1/approvals`

### Authorization

`Authorization`: Bearer token · header required

\`Authorization: Bearer <token>\` with an API key (\`sfa_\` prefix), an OAuth access token, a session token, or a Space machine credential (\`sfm_\` prefix).

### Request body

- required `application/json`
    - `kind` string required
        - Allowed: `confirmation`, `elevation`
    - `operation` string required
        - Allowed: `publish`, `deploy`, `version_rollback`, `domain_purchase`, `domain_dns_change`
    - `requestedScopes` string[]
        - max items 32 · default: []
    - `rationale` string required
        - min length 1 · max length 1024
    - `resource` object required
        - Show properties
        - `kind` string required
            - Allowed: `team`, `space`, `version`, `domain`, `connector_run`
        - `id` string required
            - min length 1
        - `revision` string | integer required

### Responses

#### 201 Response for status 201

- `\$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` string required
        - Allowed: `device_authorization`, `confirmation`, `elevation`
    - `instruction` string required
        - One sentence an agent can show a person, naming what they have to do.
    - `url` string <uri> | any
    - `pollUrl` string <uri>
    - `continuationToken` string required
        - min length 1
    - `pollAfterSeconds` integer required
        - max 9007199254740991
    - `expiresAt` string <date-time> required
        - ISO 8601 deadline for the human step. Resuming after it answers `expired`.

### Example Request

```bash
curl -X POST "https://api.spacefast.com/v1/approvals" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "kind": "confirmation",\n  "operation": "publish",\n  "requestedScopes": [],\n  "rationale": "string",\n  "resource": {\n    "kind": "team",\n    "id": "string",\n    "revision": "string"\n  },\n  "quote": null\n}'
```

### Example Response

```json
{
  "$schema": "http://example.com",
  "data": {
    "approvalId": "string"
  },
  "requiresAction": {
    "actionType": "device_authorization",
    "instruction": "string",
    "url": "http://example.com",
    "pollUrl": "http://example.com",
    "continuationToken": "string",
    "pollAfterSeconds": 9007199254740991,
    "expiresAt": "2019-08-24T14:15:22Z"
  }
}
```

### Error Response Example

```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```