Request a user decision - Spacefast Docs

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 ` 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
- 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 | any
- pollUrl string
- continuationToken string required
  - min length 1
- pollAfterSeconds integer required
  - max 9007199254740991
- expiresAt string
  required
  - ISO 8601 deadline for the human step. Resuming after it answers expired.

Example Request

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

{
  "$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

{
  "$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"
}