# Approval

> A request for a human to allow an action.

A request for a human to allow an action. When approved (with a passkey) the platform runs the stored request
as the requesting principal and records the outcome; the requester never receives a credential.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` * | string |  |
| `workspace_id` * | string |  |
| `project_id` | string or null |  |
| `environment` | string or null |  |
| `status` * | [ApprovalStatus](/docs/api/objects/approval-status/) |  |
| `action` * | object |  |
| `reason` | string or null | Why the requester wants this, in their words. |
| `why_required` | array of [PolicyReason](/docs/api/objects/policy-reason/) |  |
| `plan` | [Plan](/docs/api/objects/plan/) or any or null |  |
| `risk` | `low`, `medium`, `high`, `critical` |  |
| `approver_roles` | array of [Role](/docs/api/objects/role/) |  |
| `requested_by` * | [Actor](/docs/api/objects/actor/) |  |
| `decided_by` | [Actor](/docs/api/objects/actor/) or any or null |  |
| `decided_at` | string (date-time) or null |  |
| `decision_note` | string or null |  |
| `operation_id` | string or null | Operation started when the approved request ran. |
| `result` | object or null | Outcome of the approved request. |
| `url` * | string (uri) |  |
| `expires_at` * | string (date-time) |  |
| `created_at` * | string (date-time) |  |

\* always present

## Example

```json
{
  "id": "apr_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "workspace_id": "string",
  "project_id": "string",
  "environment": "string",
  "status": "pending",
  "action": {
    "kind": "deployment.create",
    "summary": "Deploy web (commit a1b2c3d, \"Fix rota export\") to production",
    "method": "string",
    "path": "string"
  },
  "reason": "string",
  "why_required": [
    {
      "code": "environment_protected",
      "message": "production requires approval for changes made by agents",
      "policy": "guv.environment.protection"
    }
  ],
  "plan": {
    "plan_hash": "sha256:9f2c1e0b7a4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a49",
    "dry_run": true,
    "summary": "1 to update. +£5.00/month at current usage.",
    "changes": [
      {
        "action": "update",
        "resource": {
          "type": "service",
          "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
          "name": "web"
        },
        "environment": "production",
        "summary": "Raise web memory limit from 1 GB to 2 GB",
        "diff": [
          {
            "path": "/resources/memory_mb",
            "before": 1024,
            "after": 2048
          }
        ],
        "destructive": false,
        "requires_approval": true,
        "reason": "production requires approval for changes made by agents"
      }
    ],
    "cost": {
      "current_monthly": {
        "amount": "18.20",
        "currency": "GBP",
        "display": "£18.20"
      },
      "projected_monthly": {
        "amount": "23.20",
        "currency": "GBP",
        "display": "£23.20"
      },
      "delta_monthly": {
        "amount": "5.00",
        "currency": "GBP",
        "display": "£5.00"
      },
      "confidence": "medium"
    },
    "policy": {
      "decision": "approval_required",
      "reasons": [
        {
          "code": "environment_protected",
          "message": "production requires approval for changes made by agents",
          "policy": "guv.environment.protection"
        }
      ],
      "approver_roles": [
        "owner",
        "admin"
      ]
    },
    "requires_approval": true,
    "expires_at": "2026-10-23T15:00:00Z"
  },
  "risk": "low",
  "approver_roles": [
    "owner"
  ],
  "requested_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "decided_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "decided_at": "2026-10-22T13:05:00Z",
  "decision_note": "string",
  "operation_id": "string",
  "result": {
    "status": 1,
    "body": {}
  },
  "url": "https://guv.dev/",
  "expires_at": "2026-10-22T13:05:00Z",
  "created_at": "2026-10-22T13:05:00Z"
}
```

## Used by

- [Ask a human to approve a specific request](/docs/api/approvals/#ask-a-human-to-approve-a-specific-request)
- [Get an approval request](/docs/api/approvals/#get-an-approval-request)
- [Approve a request (passkey required)](/docs/api/approvals/#approve-a-request-passkey-required)
- [Deny a request](/docs/api/approvals/#deny-a-request)
- [Withdraw a pending request (requester)](/docs/api/approvals/#withdraw-a-pending-request-requester)